root/1.8.3/trunk/game/txt/hlp/pennfunc.hlp

& FUNCTIONS
  Functions are specialized commands used to manipulate strings and
  other input. Function take the general form:  [FUNCTION(<input>)]

  The brackets are used to delimit and force evaluation of the function 
  (or nested functions). The brackets can also be used to group functions 
  for the purposes of string concatenation. In general, more than one pair 
  of brackets is not required, but you can nest an arbitrary number of
  brackets.

  Examples:
      > say [first(rest(This is a nice day))]
      You say, "is"
      > @va me=This is a 
      Wizard - Set.
      > @vb me=nice day
      Wizard - Set.
      > say [first([rest([v(va)] [v(vb)])])]
      You say, "is"

  See "help FUNCTIONS2" for more.

& FUNCTIONS2

  A list of available built-in functions can be obtained via the command
  "@config/functions". In the help text, the list is under the topic
  "FUNCTION LIST".

  In addition to these built-in functions are MUSH-defined "global user
  functions."  These are defined by wizards or those with the "Function"
  power, via the "@function" command. To the user, they act just like
  the built-in game functions. For details on global user functions,
  see "help @function".

See also: MUSHCODE
& FUNCTION LIST
  Several major variants of functions are available. The help topics
  are listed below, together with a quick summary of the function type
  and some examples of that type of function.

  Attribute functions: attribute-related manipulations (GET, UFUN)
  Bitwise functions: Manipulation of individual bits of numbers (SHL, BOR)
  Boolean functions:  produce 0 or 1 (false or true) answers  (OR, AND)
  Channel functions: Get information about channels (CTITLE, CWHO)
  Communication functions: Send messages to objects (PEMIT, OEMIT)
  Connection functions: Get information about a player's connection (CONN)
  Dbref functions: return dbref info related to objects (LOC, LEXITS)
  Html functions: output html tags for Pueblo-compatible clients
  Information functions:  find out something about objects (FLAGS, MONEY)
  List functions:  manipulate lists (REVWORDS, FIRST)
  Mail functions: manipulate @mail (MAIL, FOLDERSTATS)
  Math functions:  number manipulation, generic or integers only (ADD, DIV)
  Regular expression functions: Regular expressions (REGMATCH, REGEDIT)
  SQL functions: Access SQL databases (SQL, SQLESCAPE)
  String functions:  string manipulation (ESCAPE, FLIP)
  Time functions: Formatting and display of time (TIME, CONVSECS)
  Utility functions: general utilities (ISINT, COMP)

  The command "@config/functions" lists all of the game's built-in functions.
  The command "@function" lists all of the game's custom global functions
    defined via the @function command.

& Attribute functions
  The primary purpose of these functions is to access information
  stored in attributes on objects.

  aposs()       attrib_set()  default()     edefault()    eval()
  get()         grep()        grepi()       lattr()       nattr()
  obj()         poss()        regrep()      regrepi()     subj()
  udefault()    ufun()        uldefault()   ulocal()      v-function
  wildgrep()    wildgrepi()   xget()        zfun()

See also: ATTRIBUTES, NON-STANDARD ATTRIBUTES
& Bitwise functions
  These functions treat integers as a sequence of binary bits (Either 0
  or 1) and manipulate them.

  For example, 2 is represented as '0010' and 4 as '0100'. If these two
  numbers are bitwise-or'ed together with BOR(), the result is 6, or
  (In binary) '0110'. These functions are useful for storing small
  lists of toggle (Yes/No) options efficiently.

  baseconv()    band()        bnand()       bnot()        bor()
  bxor()        shl()         shr()

& Boolean functions
  Boolean functions all return 0 or 1 as an answer.
  Your MUSH may be configured to use traditional PennMUSH booleans,
  in which case non-zero numbers, non-negative db#'s, and strings
  are all considered "true" when passed to these functions.
  Alternatively, your MUSH may be using TinyMUSH 2.2 booleans,
  in which case only non-zero numbers are "true".

  and()         cand()        cor()         eq()          gt()
  gte()         lt()          lte()         nand()        neq()
  nor()         not()         or()          t()           xor()

See also: BOOLEAN VALUES, @config
& Communication functions
  Communication functions are side-effect functions that send a message
  to an object or objects.

  cemit()       emit()        lemit()       nsemit()      nslemit()
  nsoemit()     nspemit()     nsprompt()    nsremit()     nszemit()
  oemit()       pemit()       prompt()      remit()       zemit()
& Connection functions
  Connection functions return information about the connections open 
  on a game, or about specific connections.

  cmds()        conn()        doing()       height()      hostname()
  hidden()      idle()        ipaddr()      lports()      lwho()
  lwhoid()      mwho()        mwhoid()      nmwho()       nwho()
  player()      ports()       pueblo()      recv()        sent()
  ssl()         terminfo()    width()       xmwho()       xmwhoid()
  xwho()        xwhoid()      zmwho()       zwho()
& Dbref functions
  Dbref functions return a dbref or list of dbrefs related to some value
  on an object.

  children()    con()         entrances()   exit()        followers()
  following()   home()        lcon()        lexits()      loc()
  locate()      lparent()     lplayers()    lsearch()     lvcon()
  lvexits()     lvplayers()   namelist()    next()        nextdbref()
  num()         owner()       parent()      pmatch()      rloc()
  rnum()        room()        where()       zone()

See also: DBREF
& Information functions
  Information functions return values related to objects or the game.

  alias()       andflags()    andlflags()   andlpowers()  config()
  controls()    ctime()       elock()       findable()    flags()
  fullalias()   fullname()    hasattr()     hasattrp()    hasflag()
  haspower()    hastype()     iname()       lflags()      lock()
  lstats()      money()       mtime()       mudname()     name()
  nattr()       nearby()      objid()       objmem()      orflags()
  orlflags()    orlpowers()   playermem()   poll()        powers()
  quota()       restarts()    type()        version()     visible()
& List functions
  List functions take at least one list of elements and return transformed
  lists or one or more members of those lists. Most of these functions
  can take an arbitrary <delimiter> argument to specify what delimits
  list elements; if none is provided, a space is used by default.

  element()     elements()    extract()     filter()      filterbool()
  first()       fold()        grab()        graball()     index()
  insert()      itemize()     items()       iter()        last()
  ldelete()     map()         match()       matchall()    member()
  mix()         munge()       namegrab()    namegraball() remove()
  replace()     rest()        revwords()    setdiff()     setinter()
  setunion()    shuffle()     sort()        sortby()      sortkey()
  splice()      step()        table()       unique()      wordpos()
  words()

See also: LISTS
& Math functions
  Math functions take one or more floating point numbers and return 
  a numeric value.
  abs()         acos()        add()         asin()        atan()
  atan2()       bound()       ceil()        cos()         ctu()
  dist2d()      dist3d()      e()           exp()         fdiv()
  floor()       fmod()        fraction()    ln()          lmath()
  log()         max()         mean()        median()      min()
  mul()         pi()          power()       root()        round()
  sign()        sin()         sqrt()        stddev()      sub()
  tan()         trunc()       val()

  These functions operate only on integers (if passed floating point
  numbers, they will return an error or misbehave):
  dec()         div()         floordiv()    inc()         mod()
  remainder()

  These functions operate on n-dimensional vectors. A vector
  is a delimiter-separated list of numbers (space-separated, by default):
  vadd()        vcross()      vdim()        vdot()        vmag()
  vmax()        vmin()        vmul()        vsub()        vunit()
& Regular expression functions
  These functions take a regular expression (regexp, or re) and match
  it against assorted things.

  regedit()     regeditall() regeditalli()  regediti()    regmatch()
  regmatchi()   regrab()     regraball()    regraballi()  regrabi()
  regrep()      regrepi()    reswitch()     reswitchall() reswitchalli()
  reswitchi()

See also: string functions, regexp
& SQL functions
  These functions perform queries or other operations on an SQL
  database to which the MUSH is connected, if SQL support is
  available and enabled.

  sql()         sqlescape()   mapsql()

& String functions
  String functions take at least one string and return a transformed
  string, parts of a string, or a value related to the string(s).

  accent()      after()       align()       alphamin()    alphamax()
  art()         before()      brackets()    capstr()      case()
  caseall()     cat()         center()      comp()        chr()
  decode64()    decompose()   decrypt()     delete()      digest()
  edit()        encode64()    encrypt()     escape()      if()
  ifelse()      foreach()     lcstr()       left()        lit()
  ljust()       merge()       mid()         ord()         ordinal()
  pos()         regedit()     lpos()        regmatch()    repeat()
  reverse()     right()       rjust()       scramble()    secure()
  sha0()        space()       spellnum()    squish()      strcat()
  strinsert()   stripaccents()stripansi()   strlen()      strmatch()
  strreplace()  switch()      trim()        ucstr()       wrap()

See also: STRINGS
& Time functions
  These functions return times or format times.

  convsecs()    convutcsecs() convtime()    ctime()       etimefmt()
  isdaylight()  mtime()       restarttime() secs()        starttime()
  stringsecs()  time()        timefmt()     timestring()  utctime()

& Utility functions
  These functions don't quite fit into any other category.

  allof()       ansi()        atrlock()     beep()        checkpass()
  clone()       create()      die()         dig()         firstof()
  functions()   isdbref()     isint()       isnum()       isobjid()
  isword()      letq()        localize()    link()        list()
  lnum()        null()        numversion()  objeval()     open()
  pcreate()     r-function    rand()        s-function    scan()
  set()         setq()        setr()        soundex()     soundslike()
  speak()       tel()         textentries() textfile()    valid()
  wipe()        @@()

& @@()
& NULL()
  @@(<expression>)
  null(<expression>[, ... , <expression>])

  The @@() function does nothing and returns nothing. It could be
  used for commenting, perhaps. It does not evaluate its argument.

  The null() function is similar, but does evaluate its argument(s),
  so side-effects can occur within a null(). Useful for eating the
  output of functions when you don't use that output.
& ABS()
  abs(<number>)

  Returns the absolute value of a number. i.e. ABS(-4) returns 4;
  ABS(2) returns 2, etc.
& ACCENT()
  accent(<string>, <template>)

  The accent() function will return <string>, with characters in it
  possibly changed to accented ones according to <template>. Both
  arguments must be the same size.

  Whether or not the resulting string is actually displayed correctly
  is client-dependent. Some OSes uses different character sets than
  the one assumes (ISO 8859-1), and some clients strip these 8-bit
  characters.

  See 'HELP ACCENT2' for a description of the template argument.

See also: stripaccents(), NOACCENTS
& ACCENT2
  For each character in <string>, the corresponding character of
  <template> is checked according to the table below, and a replacement
  done. If either the current <string> or <template> characters aren't
  in the table, the <string> character is passed through unchanged.

  Accent                         Template   String
  Name       Description         Character  Character
  --------------------------------------------------------------
  grave      Backward slant      `          A,E,I,O,U,a,e,i,o,u
             above letter
  acute      Forward slant       '          A,E,I,O,U,Y,a,e,i,o,u,y
             above letter
  tilde      Wavy line above     ~          A,N,O,a,n,o
             letter
  circumflex carat above         ^          A,E,I,O,U,a,e,i,o,u
             letter
  umlaut     Two dots above      :          A,E,I,O,U,,a,e,i,o,u,y
  diaeresis  letter
  ring       Small circle above  o          A,a
             letter
  cedilla    Small tail below    ,          C,c
             letter

  See 'HELP ACCENT3' for more
& ACCENT3
  These are non-accent special characters, mostly punctuation and
  non-roman letters.

                      Template   String
  Description         Character  Character
  --------------------------------------------------------------
  Upside-down ?       u          ?
  Upside-down !       u          !
  << quote mark       "          <
  >> quote mark       "          >
  German sharp s      B          s
  Capital thorn       |          P
  Lower-case thorn    |          p
  Capital eth         -          D
  Lower-case eth      &          o
  
  See 'HELP ACCENT4' for examples
& ACCENT4
  Some examples of accent() and their expected outputs:

  > think accent(Aule, ---:)
  Aul(e-with-diaeresis)

  > think accent(The Nina was a ship, The Ni~a was a ship) 
  The Ni(n-with-~)a was a ship

  > think accent(Khazad ai-menu!, Khaz^d ai-m^nu!)
  Khaz(a-with-^)d ai-m(e-with-^)nu!
& ACCNAME()
  accname(<object>)

  accname() returns the name of object <object>, applying the object's
  @nameaccent, if any.

  Related functions: NAME(), FULLNAME(), INAME()
& ACOS()
  acos(<cosine>[,<angle type>])
 
  Returns the angle that has the given <cosine> (arc-cosine), with the
  angle expressed in the given angle type, or radians by default.

  See 'HELP CTU()' for more on the angle type.
& ADD()
  add(<number>, <number>[, ... , <numberN>])

  Returns the sum of some numbers. 
& AFTER()
  after(<string1>, <string2>)

  Returns the portion of <string1> that occurs after <string2>.
  If <string2> isn't in <string1>, the function returns a null string.
  This is case-sensitive.
 
  Examples:
   > think after(foo bar baz,bar)
    baz
   > think after(foo bar baz,ba)
   r baz

See also: before(), rest()
& ALIGN()
  align(<widths>,<col1>,...,<coln>[,<filler>[,<colsep>[,<rowsep>]]])

  Creates columns of text, each column designated by <col1..coln>.
  Each column is individually wrapped inside its own column, allowing
  for easy creation of book pages, newsletters, or the like.

  <widths> is a space-separated list of column widths. '10 10 10' for the
  widths argument specifies that there are 3 columns, each 10 spaces wide.
  < before a number causes the field to be left-aligned (the default). A
  '-' causes it to be centered, and '>' makes it right-aligned.
  A '.' after the number implies the column is to be repeated for as long
  as there is text remaining in a non-repeating column. A ` (left tick)
  after the number implies that if the column runs out of text, it should
  merge with the next leftmost column (making that column flow around).
  A ' (right tick) after the number implies that if the column runs out
  of text, it should merge with the next rightmost column.

  <filler> is a single character that, if given, is the character used
  to fill empty columns and remaining spaces. <colsep>, if given, is
  inserted between every column, on every row. <rowsep>, if given, is
  inserted between every line. By default, <filler> and <colsep> are
  a space, and <rowsep> is a newline.

  Continued in HELP ALIGN2
& ALIGN2
  Examples:
  
    > &line me=align(<5 10 20,\([left(xget(%0,sex),1)]\),name(%0),name(loc(%0)))
    > th iter(lwho(),u(line,##),%b,%r)
      (M) Walker     Tree
      (F) Jane Doe   Nowhere

    > &haiku me = Alignment function,%rIt justifies your writing,%rBut the
                  words still suck.%rLuke

    > th [align(5 -40 5,,[repeat(-,40)]%r[u(haiku)]%r[repeat(-,40)],,%b,+)

         +----------------------------------------+
         +          Alignment function,           +     
         +       It justifies your writing,       +     
         +       But the words still suck.        +     
         +                  Luke                  +
         +----------------------------------------+

See also: center(), ljust(), rjust()
& ALLOF()
  allof(<expr1>[, ... , <exprN>],<osep>)

  Evaluates every expression argument (including side-effects) and returns
  the results of those which are true, in a list separated by osep.  The
  output separator argument is required and must be a single character,
  or can be left empty, in which case a space will be used to separate the
  results by default.

  The meaning of true or false depends on configuration options as
  explained in the 'BOOLEAN VALUES' help topics.

  > &s me=Bats are similar to Rats which are afraid of Cats
  > say allof(grab(v(s),rats),grab(v(s),mats),grab(v(s),bats),)
  You say, "Rats Bats"

  > say allof(#-1,#101,#2970,,#-3,0,#319,null(This Doesn't Count),|)
  You say, "#101|#2970|#319"

See also: firstof(), BOOLEAN VALUES
& ALPHAMAX()
  alphamax(<word1>[, ... , <wordN>])

  Takes any number of arguments, and returns the word which is
  lexicographically biggest. I.e., which word would be last in 
  alphabetical order.

& ALPHAMIN()
  alphamin(<word1>[, ... , <wordN>])

  Takes any number of arguments, and returns the word which is
  lexicographically smallest: the word that would be first in
  alphabetical order.

& AND()
& CAND()
  and(<boolean value 1>, <boolean value 2>[, ... , <boolean value N>])
  cand(<boolean value 1>, <boolean value 2>[, ... , <boolean value N>])
 
  Takes boolean values, and returns 1 if all of them are equivalent
  to true(1).  and() always evaluates all arguments (including side
  effects), while cand() stops evaluation after the first argument
  that evaluates to false.

See also: BOOLEAN VALUES, or(), xor(), not()
& ANDFLAGS()
  andflags(<object>,<string of flag letters>)

  This function returns 1 if <object> has all the flags in a specified
  string, and 0 if it does not. The string is specified with a single
  letter standing for each flag, like the output of the FLAGS()
  function. A '!'  preceding a flag letter means "not flag".

  Thus, ANDFLAGS(me,WD) would return 1 if I was set WIZARD and DARK.
  ANDFLAGS(me,W!Dc) would return 1 if I was set WIZARD, not DARK,
  and CONNECTED.

  If a letter does not correspond to any flag, <object> doesn't have it,
  so the function returns 0. There can be an arbitrary number of flags. Do
  not put spaces between flag letters.
& ANDLFLAGS()
  andlflags(<object>, <list of flags>)

  This function returns 1 if <object> has all the flags in a specified
  list, and 0 if it does not. The list is a space-separated list of
  flag names.  A '!' preceding a flag name means "not flag".

  Thus, ANDLFLAGS(me,wizard dark) would return 1 if I was set WIZARD
  and DARK.  ANDFLAGS(me,wizard !Dark connected) would return 1 if I
  was set WIZARD, not DARK, and CONNECTED.

  If a name does not correspond to any flag, <object> doesn't have it,
  so the function returns 0. There can be an arbitrary number of flags.
& ANDLPOWERS()
  andlpowers(<object>, <list of powers>)

  This function returns 1 if <object> has all the powers in a
  specified list, and 0 if it does not. The list is a space-separated
  list of power names.  A '!' preceding a flag name means "not power".

  Thus, ANDLPOWERS(me, no_quota no_pay) would return 1 if I was
  powered no_quota and no_pay.  ANDLPOWERS(me, poll !guest) would
  return 1 if I could change the poll and was not a guest.

  If a name does not correspond to any power, <object> doesn't have
  it, so the function returns 0. There can be an arbitrary number of
  powers.
& ANSI()
  ansi(<codes>, <string>)
 
  This allows you to highlight a string using ANSI terminal effects.
  The codes are:
 
        f - flash                       F - not flash
        h - hilite                      H - not hilite
        u - underscore                  U - not underscore
        i - inverse                     I - not inverse
        n - normal                      

        d - default foreground          D - default background
        x - black foreground            X - black background
        r - red foreground              R - red background
        g - green foreground            G - green background
        y - yellow foreground           Y - yellow background
        b - blue foreground             B - blue background
        m - magenta foreground          M - magenta background
        c - cyan foreground             C - cyan background
        w - white foreground            W - white background
 
  For example, "ansi(fc, Test)" would hilight "Test" in flashing cyan.
  Default foreground and background use the client's default color for
  fore and back.
 
See also: ANSI, COLOR 
& APOSS()
  aposs(<object>)

  Returns the absolute possessive pronoun - his/hers/its/theirs -
  for an object.
& ART()
  art(<string>)

  This function returns the proper article, "a" or "an", based on whether
  or not <string> begins with a vowel.
& ASIN()
  asin(<sine>[,<angle type>])
 
  Returns the angle with the given <sine> (arc-sine), with the angle
  expressed in the given angle type, or radians by default.

  See 'HELP CTU()' for more on the angle type.
& ATAN()
& ATAN2()
  atan(<tangent>[,<angle type>])
  atan2(<number>, <number>[,<angle type>])

  Returns the angle with the given <tangent> (arc-tangent), with the
  angle expressed in the given angle type, or radians by default.

  atan2(y, x) is like atan(fdiv(y, x)), except x can be 0, and the
  signs of both arguments are used in determining the sign of the
  result. It is useful in converting between cartesian and polar
  coordinates.

  See 'HELP CTU()' for more on the angle type.
& ATRLOCK()
  atrlock(<object>/<attrib>[, <on|off>])

  When given a single object/attribute pair as an argument, returns 1
  if the attribute is locked, 0 if unlocked, and #-1 if the attribute
  doesn't exist or can't be read by the function's caller.

  When given a second argument of "on" (or "off"), attempts to lock
  (unlock) the specified attribute, as per @atrlock.
& ATTRIB_SET()
  attrib_set(<object>/<attrib>[, <value>])

  Sets or clears an attribute. With a value, it sets the attribute,
  without one, it clears the attribute. This is an easier-to-read
  replacement for the old set(<object>, <attrib>:<value>) notation,
  and a less destructive replacement for wipe() that won't destroy
  entire attribute trees in one shot.

  If there is a second argument, then attrib_set() will create an
  attribute, even if the second argument is empty (in which case
  attrib_set() will create an empty attribute).  This means that
  attrib_set(me/foo,%0) will _always_ create an attribute.

  Of course, if the empty_attrs configuration option is turned off,
  then the above paragraph doesn't apply.  See '@config attribs'.
  
& BAND()
  band(<integer1>, <integer2>[, ... , <integerN>])

  Does a bitwise AND of all its arguments, returning the result
  (A number with only the bits set in every argument set in it).
& BASECONV()
  baseconv(<number>, <from base>, <to base>)

  Converts <number>, which is in base <from base> into base <to base>.
  The bases can be between 2 (binary) and 36. 
& BEEP()
  beep([<number>])
 
  Sends <number> "alert" bell characters. <number> must be in the range
  1 to 5, or, if unspecified, defaults to 1.
  This function may only be used by royalty and wizards. 
 
& BEFORE()
  before(<string1>, <string2>)
 
  Returns the portion of <string1> that occurs before <string2>.
  If <string2> isn't in <string1>, <string1> is returned.
  This is case-sensitive.
 
  Examples:
   > think before(foo bar baz,bar)
   foo
   > think before(foo bar baz,r)
   foo ba

See also: after(), first()
& BRACKETS()
  brackets([<string>])

  Returns a count of the number of left and right square brackets, 
  parentheses, and curly braces in the string, in that order, as a
  space-separated list of numbers. This is useful for finding missing 
  or extra brackets in MUSH code. 

  Example:
  > @desc me=This is [ansi(h,a test)] of the { brackets() function.
  > think brackets(v(desc))
  1 1 2 2 1 0
& BNAND()
  bnand(<integer>, <integer>)

  Returns its first argument with every bit that was set in the second
  argument cleared.
& BNOT()
  bnot(<integer>)

  Returns the bitwise complement of its argument. Every bit set in it
  is cleared, and every clear bit is set.
& BOR()
  bor(<integer>, <integer>[, ... , <integerN>])

  Does a bitwise OR of all its arguments, returning the result.
  (A number with a bit set if that bit appears in any of its arguments).
& BOUND()
  bound(<number>, <lower bound>, <higher bound>)

  bound() returns <number> if it is between <lower bound> and
  <higher bound>. If it's lower than the lower bound, the lower
  bound is returned. If it's higher than the higher bound,
  the higher bound is returned.
  
See also: ceil(), floor(), round(), trunc()
& BXOR()
  bxor(<integer>, <integer>[, ... , <integerN>])

  Does a bitwise XOR of all its arguments, returning the result.
  (A number with a bit set if it's set in only one of its arguments).
& CAPSTR()
  capstr(<string>)
  
  Returns <string> with the first character capitalized.
  Example: capstr(foo bar baz) returns "Foo bar baz"

See also: lcstr(), ucstr()
& CAT()
  cat(<string1>[, ... , <stringN>])

  cat() concatenates strings, separating each string by a space.
  So "[cat(one, two)]" will return 'one two'.

See also: strcat()
& CEIL()
  ceil(<number>)
 
  Returns the least integral value greater than or equal to <number>.

See also: floor(), bound(), round(), trunc()
& CENTER()
  center(<string>, <width>[, <fill>[, <rightfill>]])
 
  This function will center <string> within a field <width> characters wide,
  using the <fill> string for padding on the left side of the string,
  and <rightfill> for padding on the right side. <rightfill> defaults
  to the mirror-image of <fill> if not specified. <fill> defaults to
  a space if neither <fill> nor <rightfill> are specified. 

  If <string> divides <width> into uneven portions, the left side
  will be one character shorter than the right side.
 
  Examples:
    > say center(X,5,-)
    You say, "--X--"
    > say center(X,5,-=)
    You say, "-=X=-"
    > say center(.NEAT.,15,-,=)
    You say, "----.NEAT.====="
    > say center(hello,16,12345)
    You say, "12345hello543215"

See also: align(), ljust(), rjust()
& CHECKPASS()
  checkpass(<player>, <string>)

  Returns 1 if <string> matches the player's password otherwise 0.
  If <player> has no password, this function will always return 1.
  <player> should be specified as a dbref or *<name>.

  This function is restricted to wizards.

& CHR()
& ORD()
  chr(<number>)
  ord(<character>)

  ord() returns the numerical value of the given character.
  chr() returns the character with the given numerical value.

  Examples:
  > think ord(A)
  65
  > think chr(65)
  A
& CLONE()
  clone(<object>)
 
  This function clones <object>, and returns the dbref number of the clone.

  This is a side-effect function and may not be enabled on some MUSHes.
& CMDS()
  cmds(<player|descriptor>)

  Returns the number of commands issued by a player during this
  connection as indicated by WHO. 

  The caller can use the function on himself, but using on any other
  player requires privileged power such as Wizard, Royalty or SEE_ALL.

See also: Connection Functions
& SENT()
  sent(<player|descriptor>)

  Returns the number of characters sent by a player during this
  connection as indicated by SESSION. 

  The caller can use the function on himself, but using on any other
  player requires privileged power such as Wizard, Royalty or SEE_ALL.

See also: Connection Functions
& RECV()
  recv(<player|descriptor>)

  Returns the number of characters received by a player during this
  connection as indicated by SESSION. 

  The caller can use the function on himself, but using on any other
  player requires privileged power such as Wizard, Royalty or SEE_ALL.

See also: Connection Functions
& COMP()
  comp(<value1>, <value2>[,<type>])

  Comp compares two values.  It returns 0 if they are the same, -1 if
  value1 is less than/precedes alphabetically value2, and 1 
  otherwise.

  By default the comparison is a case-sensitive lexicographic (string)
  comparison. By giving the optional <type>, the comparison can
  be specified:
      <type>            Comparison
        A               Maybe case-sensitive lexicographic (default)
        I               Always case-insensitive lexicographic
        D               Dbrefs of valid objects
        N               Integers
        F               Floating point numbers

  Whether or not the a sort type is case-sensitive or not depends
  on the particular mush and its environment.
& CON()
  con(<object>)

  Returns the dbref of the first object in a container.

  You can get the complete contents of any container you may examine,
  regardless of whether or not objects are dark.  You can get the
  partial contents (obeying DARK/LIGHT/etc.) of your current location
  or the enactor (%#).  You CANNOT get the contents of anything else,
  regardless of whether or not you have objects in it.

See also: lcon(), next()
& COND()
& CONDALL()
& NCOND()
& NCONDALL()
  cond(<cond1>, <expr1>, [<condN>, <exprN>], ...[<default>])
  condall(<cond1>, <expr1>, [<condN>, <exprN>], ...[<default>])
  ncond(<cond1>, <expr1>, [<condN>, <exprN>], ...[<default>])
  ncondall(<cond1>, <expr1>, [<condN>, <exprN>], ...[<default>])

  cond() evaluates <cond>s until one returns a boolean true value. Should
  none return true, <default> is returned.

  condall() returns all <expr>s for those <cond>s that evaluate to true.

  ncond() and ncondall() are identical to cond(), except it returns <expr>s
  for which <cond>s evaluate to false.

  Examples:
  > say cond(0,This is false,#-1,This is also false,#123,This is true)
  You say, "This is true"

  > say ncond(0,This is false,#-1,This is also false,#123,This is true)
  You say, "This is false"
  
  > say ncondall(0,This is false,#-1,This is also false,#123,This is true)
  You say, "This is falseThis is also false"
& CONFIG()
  config()
  config(<option>)

  With no arguments, this function returns a list of config option names.
  Given a config option name, this function returns its value.
  Boolean configuration options will return values of "Yes" or "No".

  Ex: config(money_singular) => "Penny"

& CONN()
  conn(<player|descriptor>)
 
  This function returns the number of seconds a player has been connected.
  <player name> must be the full name of a player, or a player's dbref.
  Players who are not connected have a conn value of "-1", as do dark
  wizards, when conn() is used on them by a non-priv'ed player.
 
See also: CONNECTED
& CONTROLS()
  controls(<object>, <victim>)
  
  This function returns 1 if <object> controls <victim>, or 0, if
  it does not. If one of the objects does not exist, it will return
  #-1 ARGN NOT FOUND (where N is the argument which is the invalid
  object). You must control <object> or <victim>, or have the See_All
  power, to use this function.

See also: CONTROL
  
& CONVSECS()
& CONVUTCSECS()
  convsecs(<seconds>[, <zone>])
  convutcsecs(<seconds>) 

  This function converts seconds to a time string, based on how many
  seconds the number is after Jan 1, 1970 UTC. Because it's based on
  UTC, but returns local time, convsecs(0) is not going to be
  "Thu Jan 1 00:00:00 1970" unless you're in the UTC (GMT) timezone.
 
  convutcsecs() and convsecs() with a second argument of 'utc' return
  the time based on UTC time instead of the server's local time.
  
  Examples:
  > say [secs()]
  You say, "709395750"
  > say [convsecs(709395750)]
  You say, "Wed Jun 24 10:22:54 1992"
  > say [convutcsecs(709395750)]
  You say, "Wed Jun 24 14:22:30 1992"

See also: convtime(), time()
& CONVTIME()
  convtime(<time string>)

  This functions converts a time string (in the local time zone) to the
  number of seconds since Jan 1, 1970 GMT. A time string is of the
  format: Ddd MMM DD HH:MM:SS YYYY where Ddd is the day of the week,
  MMM is the month, DD is the day of the month, HH is the hour in
  24-hour time, MM is the minutes, SS is the seconds, and YYYY is the
  year.  If you supply an incorrectly formatted string, it will return
  -1.

  If the extended convtime() is supported (See @config compile), more
  formats for the date are enabled, including ones missing the day
  of week and year, and a 'Month Day Year' format.

  Example:
  > say [time()]
  You say, "Wed Jun 24 10:22:54 1992"
  > say [convtime(Wed Jun 24 10:22:54 1992)]
  You say, "709395774"

See also: convsecs(), time()
& COS()
  cos(<angle>[,<angle type>])
 
  Returns the cosine of <angle>. Angle must be in the given angle
  type, or radians by default. 

  Examples:
  > say cos(90, d)
  You say, "0" 
  > say cos(1.570796)
  You say, "0"

  See 'HELP CTU()' for more on the angle type.
& PCREATE()
  pcreate(<name>, <password>)

  Creates a player with a given name and password. Wizard-only.

See also: @pcreate
& CREATE()
  create(<object>, <cost>)
 
  This function creates an object with name <object> for <cost> pennies,
  and returns the dbref number of the created object.

  This is a side-effect function and may not be enabled on some MUSHes.
& CTIME()
& CSECS()
  ctime(<object>[, <utc>])
  csecs(<objecct>)
 
  If creation times are enabled, this function will return the 
  date and time that the object was created. If the optional <utc>
  argument is true, the time is returned for the UTC time zone, if
  false or present, for the local time zone.
 
  csecs() returns the time as the number of seconds since the epoch.

  You must be able to examine an object to see its creation time.

See also: mtime()
& CTU()
  ctu(<angle>,<from>,<to>)

  Converts between the different ways to measure angles.
  <from> controls what the angle is treated as, and <to> what form
  it is turned into. They can be 'd' for degrees, or 'r' for radians.
  There is also a third way to measure angle, 'g' for gradians, but it's not
  used often and is only included for completeness.

  As a refresher, there are 180 degrees in pi radians in 200 gradians.

  Example:
  > say 90 degrees is [ctu(90, d, r)] radians
  You say, "90 degrees is 1.570796 radians"
& DEC()
  dec(<integer>)
  dec(<string-ending-in-integer>)

  Dec returns the integer minus 1. If given a string that ends in an integer,
  it decrements only the final integer portion. That is:

  > think dec(3)
  2
  > think dec(hi3)
  hi2
  > think dec(1.3.3)
  1.3.2
  > think dec(1.3)
  1.2

  Note especially the last example, which will trip you up if you use
  floating point numbers with dec() and expect it to work like sub().

See also: inc()
& DECOMPOSE()
  decompose(<string>)

  decompose() works like escape() with the additional caveat that it inserts
  parse-able characters to recreate <string> exactly after one parsing. It
  takes care of multiple spaces, '%r's, and '%t's.

See also: @decompile2, escape(), secure()
& DECODE64()
  decode64(<string>)

  Converts the base 64-encoded <string> back to its original form.

  Requires SSL support; see @config compile.

See also: encode64()
& DECRYPT()
  decrypt(<string>, <password>[, <encoded>])

  Decrypts a string encrypted with the encrypt() function, if given
  the string and the same password.

  If the optional <encoded> argument is true, it indicates that the
  input string is encoded in base 64.

See also: encrypt(), encode64()
& DEFAULT()
  default([<obj>/]<attr>[, ... ,[<obj>]/<attr>], <default case>)
 
  This function returns the value of the first possible <obj>/<attr>,
  as if retrieved via the get() function, if the attribute exists and
  is readable by you.  Otherwise, it evaluates the default case, and
  returns that.  Note that the default case is only evaluated if the
  attribute does not exist or cannot be read. Note further than an empty
  attribute counts as an existing attribute.

  This is useful for code that needs to return the value of an attribute,
  or an error message or default case, if that attribute does not exist.
 
  Examples:
    > &TEST me=apple orange banana
    > say default(me/Test, No fruits!)
    You say "apple orange banana"
    > &TEST ME
    > say default(me/Test, No fruits!)
    You say "No fruits!"
 
See also: get(), eval(), ufun(), edefault(), udefault(), uldefault()
 
& DELETE()
  delete(<string>, <first>, <len>)
 
  Return a modified <string>, with <len> characters starting after the
  character at position <first> deleted. In other words, it copies <first>
  characters, skips <len> characters>, and then copies the remainder of
  the string. If <len> is negative, deletes characters leftwards from <first>.
  Characters are numbered starting at 0. 

  Examples:
    > say delete(abcdefgh, 3, 2)
    You say, "abcfgh"
    > say delete(abcdefgh, 3, -2)
    You say, "abefgh"

See also: strreplace()
& DIE()
  die(<number of times to roll die>, <number of sides on die>[, <show>])
 
  This function simulates rolling dice. It "rolls" a die with a given
  number of sides, a certain number of times, and sums the results.
  For example, DIE(2, 6) would roll "2d6" - two six-sided dice,
  generating a result in the range 2-12. The maximum number of
  dice this function will roll in a single call is 20.
  If a third argument is given and it's a true value, the result will
  be a space-seperated list of the individual rolls rather than their
  sum.

  Examples:
  > think die(3, 6)
  6
  > think die(3, 6, 1)
  5 2 1  
& DIG()
  dig(<name>[, <exit to>[, <exit from>]])
 
  This function digs a room called <name>, and optionally opens and links
  <exit to> and <exit from>, like the normal @dig command. It returns
  the dbref number of the new room.

  This is a side-effect function and may not be enabled on some MUSHes.
& DIGEST()
  digest(<algorithm>, <string>)

  Returns a checksum (Hash, digest, etc.) of <string> using the given
  <algorithm>. If the mush is compiled with SSL support (See @config
  compile), <algorithm> can be one of:

  md2 md4 md5 sha sha1 dss1 mdc2 ripemd160

  Without SSL, only the sha algorithm is enabled. In both cases, sha returns
  the same thing as the sha0() function.

See also: sha0()
& DIST2D()
  dist2d(<x1>, <y1>, <x2>, <y2>)

  Returns the distance between two points in the Cartesian
  plane that have coordinates (<x1>, <y1>) and (<x2>, <y2>).
& DIST3D()
  dist3d(<x1>, <y1>, <z1>, <x2>, <y2>, <z2>)

  Returns the distance between two points in space, with
  coordinates (<x1>, <y1>, <z1>) and (<x2>, <y2>, <z2>).
& DIV()
& FLOORDIV()
  div(<number>, <number>)
  floordiv(<number>, <number>)
 
  Div returns the integer part of the quotient of the first number
  divided by the second number.  Floordiv returns the largest integer
  less than or equal to the quotient of the first number divided by
  the second.  For positive numbers, these are the same thing, but
  for negative numbers they may be different:

   div(13,4)          ==>  3       and     floordiv(13,4)     ==>  3
   div(-13,4)         ==>  -3      but     floordiv(-13,4)    ==>  -4
   div(13,-4)         ==>  -3      but     floordiv(13,-4)    ==>  -4
   div(-13,-4)        ==>  3       and     floordiv(-13,-4)   ==>  3

  Note that add(mul(div(%0,%1),%1),remainder(%0,%1)) always yields %0,
  and add(mul(floordiv(%0,%1),%1),modulo(%0,%1)) also always yields %0.

See also: modulo(), fdiv()
& DOING()
  doing(<player|descriptor>)

  Given the name of a connected player, returns that player's @doing
  string if they can be seen on the WHO list.

See also: @poll, @doing, poll()
& E()
  e()
 
  Returns the value of "e"  (2.71828182845904523536, rounded to the
  game's float_precision setting).
& EDEFAULT()
  edefault([<obj>/]<attr>, <default case>)
 
  This function returns the evaluated value of <obj>/<attr>, as if
  retrieved via the get_eval() function, if the attribute exists and
  is readable by you. Otherwise, it evaluates the default case, and
  returns that. The default case is only evaluated if the attribute
  does not exist or cannot be read.
 
  Example:
    > &TEST me=You have lost [rand(10)] marbles.
    > say edefault(me/Test,You have no marbles.)
    You say "You have lost 6 marbles."
    > &TEST me
    > say edefault(me/Test,You have no marbles.)
    You say "You have no marbles."
  
See also: get(), eval(), ufun(), default(), udefault()
 
& EDIT()
  edit(<string>, <search>, <replace>[, ... , <searchN>, <replaceN>])
 
  This functions in a similar way to the @edit command; instead of
  taking an attribute from an object, it takes an arbitrary string.
  It searches the string for <search> and replaces with <replace>,
  then repeats the process if additional search-replace pairs are
  given.

  If <search> is a caret (^), <replace> is prepended.
  If <search> is a dollar sign ($), <replace> is appended.
  If <search> is an empty string, <replace> is inserted between
  every character, and before the first and after the last.
  If <replace> is an empty string, <search> is deleted from the string.

  Example:
  > say [edit(this is a test,^,I think%b,$,.,a test,an exam)]
  You say "I think this is an exam." 

  edit() can not replace a literal single ^ or $. Use regedit() for that.
  
See also: @edit, regedit()
& ELEMENT()
  element(&l