                 /----------------------------------------\
                <      util.pkg functions helper file      >
                 \----------------------------------------/

    ----------------------------------------------------------------------

    === bst ===

    Declaration
        s32b bst(s32b what, s32b t);

    File
        util.c

    Comment
    /*
     * Break scalar time
     */

    Description
    Return the minute, hour, day, or year for turn "t". One turn takes 7.5
    seconds.

    Parameters
    > "what" is the unit to be returned and must be one of
      MINUTE (number of turns per minute, which is 8)
      HOUR   (number of turns per hour, which is 480)
      DAY    (number of turns per day, which is 11,520)
      YEAR   (number of turns per year, which is 4,204,800)
    > "t" is the number of turns.

    ----------------------------------------------------------------------

    === path_build ===

    Declaration
        errr path_build(char *buf, int max, cptr path, cptr file);

    File
        util.c

    Comment
    /*
    * Create a new path by appending a file (or directory) to a path
    *
    * This requires no special processing on simple machines, except
    * for verifying the size of the filename, but note the ability to
    * bypass the given "path" with certain special file-names.
    *
    * Note that the "file" may actually be a "sub-path", including
    * a path and a file.
    *
    * Note that this function yields a path which must be "parsed"
    * using the "parse" function above.
    */

    Description
    Append file "file" to path "path" and return the result in "buf". The
    length of "buf" is a maximum of "max" characters. If "file" starts
    with '~' then return "file". If "file" starts with the path separator
    and the path separator is not blank then return "file". If there is no
    path then return "file". Otherwise return "path" + path separator +
    "file". The path separator is defined in "H-config.h".

    Parameters
    > "buf" contains the new path.
    > "max" is the maximum number of characters allowed in "buf".
    > "path" is the original path.
    > "file" is the original file.

    ----------------------------------------------------------------------

    === move_cursor ===

    Declaration
        void move_cursor(int row, int col);

    File
        util.c

    Comment
    /*
    * Move the cursor
    */

    Description
    Move the cursor to row "row" and column "col".

    Parameters
    > "row" is the row the cursor is to be moved to.
    > "col" is the column the cursor is to be moved to.

    ----------------------------------------------------------------------

    === inkey ===

    Declaration
        char inkey(void);

    File
        util.c

    Comment
    /*
    * Get a keypress from the user.
    *
    * This function recognises a few "global parameters".  These are variables
    * which, if set to TRUE before calling this function, will have an effect
    * on this function, and which are always reset to FALSE by this function
    * before this function returns.  Thus they function just like normal
    * parameters, except that most calls to this function can ignore them.
    *
    * If "inkey_xtra" is TRUE, then all pending keypresses will be flushed,
    * and any macro processing in progress will be aborted.  This flag is
    * set by the "flush()" function, which does not actually flush anything
    * itself, but rather, triggers delayed input flushing via "inkey_xtra".
    *
    * If "inkey_scan" is TRUE, then we will immediately return "zero" if no
    * keypress is available, instead of waiting for a keypress.
    *
    * If "inkey_base" is TRUE, then all macro processing will be bypassed.
    * If "inkey_base" and "inkey_scan" are both TRUE, then this function will
    * not return immediately, but will wait for a keypress for as long as the
    * normal macro matching code would, allowing the direct entry of macro
    * triggers.  The "inkey_base" flag is extremely dangerous!
    *
    * If "inkey_flag" is TRUE, then we will assume that we are waiting for a
    * normal command, and we will only show the cursor if "hilite_player" is
    * TRUE (or if the player is in a store), instead of always showing the
    * cursor.  The various "main-xxx.c" files should avoid saving the game
    * in response to a "menu item" request unless "inkey_flag" is TRUE, to
    * prevent savefile corruption.
    *
    * If we are waiting for a keypress, and no keypress is ready, then we will
    * refresh (once) the window which was active when this function was called.
    *
    * Note that "back-quote" is automatically converted into "escape" for
    * convenience on machines with no "escape" key.  This is done after the
    * macro matching, so the user can still make a macro for "backquote".
    *
    * Note the special handling of "ascii 30" (ctrl-caret, aka ctrl-shift-six)
    * and "ascii 31" (ctrl-underscore, aka ctrl-shift-minus), which are used to
    * provide support for simple keyboard "macros".  These keys are so strange
    * that their loss as normal keys will probably be noticed by nobody.  The
    * "ascii 30" key is used to indicate the "end" of a macro action, which
    * allows recursive macros to be avoided.  The "ascii 31" key is used by
    * some of the "main-xxx.c" files to introduce macro trigger sequences.
    *
    * Hack -- we use "ascii 29" (ctrl-right-bracket) as a special "magic" key,
    * which can be used to give a variety of "sub-commands" which can be used
    * any time.  These sub-commands could include commands to take a picture of
    * the current screen, to start/stop recording a macro action, etc.
    *
    * If "angband_term[0]" is not active, we will make it active during this
    * function, so that the various "main-xxx.c" files can assume that input
    * is only requested (via "Term_inkey()") when "angband_term[0]" is active.
    *
    * Mega-Hack -- This function is used as the entry point for clearing the
    * "signal_count" variable, and of the "character_saved" variable.
    *
    * Hack -- Note the use of "inkey_next" to allow "keymaps" to be processed.
    *
    * Mega-Hack -- Note the use of "inkey_hack" to allow the "Borg" to steal
    * control of the keyboard from the user.
    */

    Description
    Get a keypress from the user.

    ----------------------------------------------------------------------

    === cmsg_print ===

    Declaration
        void cmsg_print(byte color, cptr msg);

    File
        util.c

    Comment
    /*
    * Output a message to the top line of the screen.
    *
    * Break long messages into multiple pieces (40-72 chars).
    *
    * Allow multiple short messages to "share" the top line.
    *
    * Prompt the user to make sure he has a chance to read them.
    *
    * These messages are memorised for later reference (see above).
    *
    * We could do "Term_fresh()" to provide "flicker" if needed.
    *
    * The global "msg_flag" variable can be cleared to tell us to
    * "erase" any "pending" messages still on the screen.
    *
    * XXX XXX XXX Note that we must be very careful about using the
    * "msg_print()" functions without explicitly calling the special
    * "msg_print(NULL)" function, since this may result in the loss
    * of information if the screen is cleared, or if anything is
    * displayed on the top line.
    *
    * XXX XXX XXX Note that "msg_print(NULL)" will clear the top line
    * even if no messages are pending.  This is probably a hack.
    */

    Description
    In color "color", output message "msg" to the top line of the screen.
    If the message is blank or has more than 1000 characters, nothing is
    printed. Long messages are split after the 40th character and before
    the 72nd character.

    Parameters
    > "color" is the color of the message.
      colors
    > "msg" is the message.

    ----------------------------------------------------------------------

    === msg_print ===

    Declaration
        void msg_print(cptr msg);

    File
        util.c

    Comment
    /* Hack -- for compatibility and easy sake */

    Description
    Print message "msg" in white (see cmsg_print() above).

    Parameters
    > "msg" is the message.

    ----------------------------------------------------------------------

    === screen_save ===

    Declaration
        void screen_save(void);

    File
        util.c

    Comment
    /*
     * Save the screen, and increase the "icky" depth.
     *
     * This function must match exactly one call to "screen_load()".
     */

    Description
    Save a screen shot.

    ----------------------------------------------------------------------

    === screen_load ===

    Declaration
        void screen_load(void);

    File
        util.c

    Comment
    /*
     * Load the screen, and decrease the "icky" depth.
     *
     * This function must match exactly one call to "screen_save()".
     */

    Description
    Load a previously saved screen shot.

    ----------------------------------------------------------------------

    === c_put_str ===

    Declaration
        void c_put_str(byte attr, cptr str, int row, int col);

    File
        util.c

    Comment
    /*
    * Display a string on the screen using an attribute.
    *
    * At the given location, using the given attribute, if allowed,
    * add the given string.  Do not clear the line.
    */

    Description
    Put string "str" at row "row" and column "col" with attribute "attr".

    Parameters
    > "attr" is the color of the message.
      colors
    > "msg" is the message.
    > "row" is the row the message is to be printed at.
    > "col" is the column the message is to be printed at.

    ----------------------------------------------------------------------

    === c_prt ===

    Declaration
        void c_prt(byte attr, cptr str, int row, int col);

    File
        util.c

    Comment
    /*
    * Display a string on the screen using an attribute, and clear
    * to the end of the line.
    */

    Description
    Clear row "row" from column "col". Put string "str" at "row", "col"
    with attribute "attr".

    Parameters
    > "attr" is the color of the message.
      colors
    > "msg" is the message.
    > "row" is the row the message is to be printed at.
    > "col" is the column the message is to be printed at.

    ----------------------------------------------------------------------

    === clear_from ===

    Declaration
        void clear_from(int row);

    File
        util.c

    Comment
    /*
    * Clear part of the screen
    */

    Description
    Clear the screen from row "row" onwards.

    Parameters
    > "row" is the first row of the screen to be cleared.

    ----------------------------------------------------------------------

    === askfor_aux ===

    Declaration
        bool askfor_aux(char *buf, int len);

    File
        util.c

    Comment
    /*
    * Get some input at the cursor location.
    * Assume the buffer is initialized to a default string.
    * Note that this string is often "empty" (see below).
    * The default buffer is displayed in yellow until cleared.
    * Pressing RETURN right away accepts the default entry.
    * Normal chars clear the default and append the char.
    * Backspace clears the default or deletes the final char.
    * ESCAPE clears the buffer and the window and returns FALSE.
    * RETURN accepts the current buffer contents and returns TRUE.
    */

    Description
    Get string "buf" from the screen. "buf" is to be no more than "len"
    bytes. The string starts at the current cursor position. The length
    can not exceed the number of bytes from the cursor to the end of the
    line. Accept user input until the escape or return key is pressed.

    Parameters
    > "buf" is the string returned from the screen.
    > "len" is the length of the string. If it is <1 it is forced to 1.

    ----------------------------------------------------------------------

    === get_string ===

    Declaration
        bool get_string(cptr prompt, char *buf, int len);

    File
        util.c

    Comment
    /*
    * Get a string from the user
    *
    * The "prompt" should take the form "Prompt: "
    *
    * Note that the initial contents of the string is used as
    * the default response, so be sure to "clear" it if needed.
    *
    * We clear the input, and return FALSE, on "ESCAPE".
    */

    Description
    Print prompt "prompt" at the top-left corner of the screen and return
    response "buf" which will have a maximum length "length". If ESCAPE
    is entered, the function returns FALSE, otherwise it returns TRUE.

    Parameters
    > "prompt" is the prompt for input.
    > "buf" is the returned response.
    > "len" is the maximum length of the string.

    ----------------------------------------------------------------------

    === get_check ===

    Declaration
        bool get_check(cptr prompt);

    File
        util.c

    Comment
    /*
    * Verify something with the user
    *
    * The "prompt" should take the form "Query? "
    *
    * Note that "[y/n]" is appended to the prompt.
    */

    Description
    Ask the user question "prompt" which requires a yes/no answer. The
    prompt appears in the top-left corner of the screen. A response of
    'Y' (either case) returns TRUE. A response of 'N' (either case) or
    ESCAPE returns FALSE.

    Parameters
    > "prompt" is the question asked. It has a maximum length of 70
      characters.

    ----------------------------------------------------------------------

    === get_com_lua ===

    Declaration
        bool get_com_lua @ get_com(cptr promtp, int *com);

    File
        util.c

    Comment
    /*
    * Prompts for a keypress
    *
    * The "prompt" should take the form "Command: "
    *
    * Returns TRUE unless the character is "Escape"
    */

    Description
    Ask the user for command "prompt" and return the key press "com". A
    response of ESCAPE returns FALSE. All other responses return TRUE.

    Parameters
    > "prompt" is the prompt for the key press.
    > "com" is the returned key press.

    ----------------------------------------------------------------------

    === get_quantity ===

    Declaration
        s32b get_quantity(cptr prompt, s32b max);

    File
        util.c

    Comment
    /*
    * Request a "quantity" from the user
    *
    * Hack -- allow "command_arg" to specify a quantity
    */

    Description
    Ask the user for quantity "prompt" of maximum value "max" and return
    a quantity. If the user quantity is higher than the maximum then the
    maximum is returned. If the response is a letter then the maximum is
    returned. If the user quantity is negative then zero is returned.

    Parameters
    > "prompt" is the prompt for a quantity.
    > "max" is the maximum value allowed.

    ----------------------------------------------------------------------

    === test_monster_name ===

    Declaration
        int test_monster_name(cptr name);

    File
        util.c

    Comment
    /*
     * Given monster name as string, return the index in r_info array. Name
     * must exactly match (look out for commas and the like!), or else 0 is
     * returned. Case doesn't matter. -GSN-
     */

    Description
    Return the monster index for monster with name "name". If no match is
    found then zero is returned.

    Parameters
    > "name" is the monster name.

    ----------------------------------------------------------------------

    === test_item_name ===

    Declaration
        int test_item_name(cptr name);

    File
        util.c

    Comment
    /*
     * Given item name as string, return the index in k_info array. Name
     * must exactly match (look out for commas and the like!), or else 0 is
     * returned. Case doesn't matter. -DG-
     */

    Description
    Return the item index for item with name "name". If no match is found
    then zero is returned.

    Parameters
    > "name" is the item name.

    ----------------------------------------------------------------------

    === luck ===

    Declaration
        int luck(int min, int max);

    File
        xtra1.c

    Comment
    /*
     * Return a luck number between a certain range
     */

    Description
    Return a number for luck between minimum "min" and maximum "max". The
    value begins with the player's current luck. The value is forced to
    be between -30 and +30. 30 is added to give a value between 0 and 60.
    The value is multiplied by the range (maximum - minimum) and divided
    by 60. The value is increased by the minimum. The value is returned.

    For example, if the player's current luck is 15, the minimum is -10,
    and the maximum is 10 (range 20), then the value returned is
    (45 * 20) / 60 which is 900 / 60 which is 15 + the minimum -10 gives
    a returned value of 5.

    Parameters
    > "min" is the minimum luck.
    > "max" is the maximum luck. Beware: this should be greater than the
      minimum but it is not checked!

    ----------------------------------------------------------------------

    === get_player_race_name ===

    Declaration
        cptr get_player_race_name(int pr, int ps);

    File
        util.c

    Comment
    (none)

    Description
    Return the name for player race "pr" and player sub-race "ps".

    Parameters
    > "pr" is the index for player race.
    > "ps" is the index for player sub-race.

    ----------------------------------------------------------------------

    === quit ===

    Declaration
        void quit(cptr str);

    File
        z-util.c

    Comment
    /*
     * Exit (ala "exit()").  If 'str' is NULL, do "exit(0)".
     * If 'str' begins with "+" or "-", do "exit(atoi(str))".
     * Otherwise, plog() 'str' and exit with an error code of -1.
     * But always use 'quit_aux', if set, before anything else.
     */

    Description
    Quit the game. If "str" is a string then write the string to the
    error file or screen. If "str" is a number then exit with the
    number as the exit code.

    Parameters
    > "str" is an error message or exit code.

    ----------------------------------------------------------------------

    === dump_hooks ===

    Declaration
        void dump_hooks();

    File
        plots.c

    Comment
    (none)

    Description
    Print the name and type (C or Lua) of hooks in the hook list.

    ----------------------------------------------------------------------

    === add_hook_script ===

    Declaration
        void add_hook_script(int h_idx, char *script, cptr name);

    File
        plots.c

    Comment
    (none)

    Description
    To hook list with index "h_idx", add a script with script file
    "script" and name "name" as a Lua hook if a hook with that name
    does not already exist.

    Parameters
    > "h_idx" is the index of the hook list in the array of hook lists.
    > "script" is the name of the script file.
    > "name" is the name of the hook to be added.

    ----------------------------------------------------------------------

    === del_hook_name ===

    Declaration
        void del_hook_name(int h_idx, cptr name);

    File
        plots.c

    Comment
    (none)

    Description
    Search hook list with index "h_idx" and remove the hook with name
    "name".

    Parameters
    > "h_idx" is the index of the hook list in the array of hook lists.
    > "name" is the name of the hook to be removed.

    ----------------------------------------------------------------------

    === pern_dofile ===

    Declaration
        bool pern_dofile(char *file);

    File
        script.c

    Comment
    (none)

    Description
    Parse the Lua script file "file".

    Parameters
    > "file" is the Lua script file to be parsed.

    ----------------------------------------------------------------------

    === intMod ===

    Declaration
        s32b intMod(s32b a, s32b b);

    File
        script.c

    Comment
    (none)

    Description
    Return the result of operation "a" mod  "b" (a % b).

    Parameters
    > "a" is a number.
    > "b" is a number.

    ----------------------------------------------------------------------

    === intAnd ===

    Declaration
        s32b intAnd(s32b a, s32b b);

    File
        script.c

    Comment
    (none)

    Description
    Return the result of bitwise operation "a" AND "b" (a & b).

    Parameters
    > "a" is a number.
    > "b" is a number.

    ----------------------------------------------------------------------

    === intOr ===

    Declaration
        s32b intOr(s32b a, s32b b);

    File
        script.c

    Comment
    (none)

    Description
    Return the result of bitwise operation "a" OR "b" (a | b).

    Parameters
    > "a" is a number.
    > "b" is a number.

    ----------------------------------------------------------------------

    === intXor ===

    Declaration
        s32b intXor(s32b a, s32b b);

    File
        script.c

    Comment
    (none)

    Description
    Return the result of bitwise operation "a" XOR "b" (a ^ b).

    Parameters
    > "a" is a number.
    > "b" is a number.

    ----------------------------------------------------------------------

    === intShiftl ===

    Declaration
        s32b intShiftl(s32b a, s32b b);

    File
        script.c

    Comment
    (none)

    Description
    Return the result of bitwise operation "a" << "b".

    Parameters
    > "a" is a number.
    > "b" is a number.

    ----------------------------------------------------------------------

    === intShiftr ===

    Declaration
        s32b intShiftr(s32b a, s32b b);

    File
        script.c

    Comment
    (none)

    Description
    Return the result of bitwise operation "a" >> "b".

    Parameters
    > "a" is a number.
    > "b" is a number.

    ----------------------------------------------------------------------

    === intBitNot ===

    Declaration
        s32b intBitNot(s32b b);

    File
        script.c

    Comment
    (none)

    Description
    Return the result of bitwise operation NOT "b" (~ b).

    Parameters
    > "b" is a number.

    ----------------------------------------------------------------------

    === register_savefile ===

    Declaration
        void register_savefile(int num);

    File
        loadsave.c

    Comment
    /*
     * Add num slots to the savefile
     */

    Description
    Add "num" slots to the save file.

    Parameters
    > "num" is the number of slots to add to the savefile. If num is <0
      then "num" is forced to zero.

    ----------------------------------------------------------------------

    === save_number_key ===

    Declaration
        void save_number_key(char *key, s32b val);

    File
        util.c

    Comment
    (none)

    Description
    Save the length of key "key", the key itself, and the value "val" as
    bytes in the savefile.

    Parameters
    > "key" is the key string for the value.
    > "val" is the value to be saved.

    ----------------------------------------------------------------------

    Back to the lua help index .

                                                         This file by Chris Hadgis