|||||oy

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

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

#####R=== bst ===

#####GDeclaration
    s32b bst(s32b what, s32b t);

#####GFile
    util.c

#####GComment
/*
 * Break scalar time
 */

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

#####GParameters
> "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.

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

#####R=== path_build ===

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

#####GFile
    util.c

#####GComment
/*
* 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.
*/

#####GDescription
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".

#####GParameters
> "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.

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

#####R=== move_cursor ===

#####GDeclaration
    void move_cursor(int row, int col);

#####GFile
    util.c

#####GComment
/*
* Move the cursor
*/

#####GDescription
Move the cursor to row "row" and column "col".

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

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

#####R=== inkey ===

#####GDeclaration
    char inkey(void);

#####GFile
    util.c

#####GComment
/*
* 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.
*/

#####GDescription
Get a keypress from the user.

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

#####R=== cmsg_print ===

#####GDeclaration
    void cmsg_print(byte color, cptr msg);

#####GFile
    util.c

#####GComment
/*
* 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.
*/

#####GDescription
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.

#####GParameters
> "color" is the color of the message.
  *****fields.txt*0[colors]
> "msg" is the message.

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

#####R=== msg_print ===

#####GDeclaration
    void msg_print(cptr msg);

#####GFile
    util.c

#####GComment
/* Hack -- for compatibility and easy sake */

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

#####GParameters
> "msg" is the message.

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

#####R=== screen_save ===

#####GDeclaration
    void screen_save(void);

#####GFile
    util.c

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

#####GDescription
Save a screen shot.

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

#####R=== screen_load ===

#####GDeclaration
    void screen_load(void);

#####GFile
    util.c

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

#####GDescription
Load a previously saved screen shot.

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

#####R=== c_put_str ===

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

#####GFile
    util.c

#####GComment
/*
* 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.
*/

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

#####GParameters
> "attr" is the color of the message.
  *****fields.txt*0[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.

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

#####R=== c_prt ===

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

#####GFile
    util.c

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

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

#####GParameters
> "attr" is the color of the message.
  *****fields.txt*0[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.

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

#####R=== clear_from ===

#####GDeclaration
    void clear_from(int row);

#####GFile
    util.c

#####GComment
/*
* Clear part of the screen
*/

#####GDescription
Clear the screen from row "row" onwards.

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

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

#####R=== askfor_aux ===

#####GDeclaration
    bool askfor_aux(char *buf, int len);

#####GFile
    util.c

#####GComment
/*
* 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.
*/

#####GDescription
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.

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

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

#####R=== get_string ===

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

#####GFile
    util.c

#####GComment
/*
* 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".
*/

#####GDescription
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.

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

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

#####R=== get_check ===

#####GDeclaration
    bool get_check(cptr prompt);

#####GFile
    util.c

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

#####GDescription
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.

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

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

#####R=== get_com_lua ===

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

#####GFile
    util.c

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

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

#####GParameters
> "prompt" is the prompt for the key press.
> "com" is the returned key press.

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

#####R=== get_quantity ===

#####GDeclaration
    s32b get_quantity(cptr prompt, s32b max);

#####GFile
    util.c

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

#####GDescription
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.

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

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

#####R=== test_monster_name ===

#####GDeclaration
    int test_monster_name(cptr name);

#####GFile
    util.c

#####GComment
/*
 * 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-
 */

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

#####GParameters
> "name" is the monster name.

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

#####R=== test_item_name ===

#####GDeclaration
    int test_item_name(cptr name);

#####GFile
    util.c

#####GComment
/*
 * 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-
 */

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

#####GParameters
> "name" is the item name.

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

#####R=== luck ===

#####GDeclaration
    int luck(int min, int max);

#####GFile
    xtra1.c

#####GComment
/*
 * Return a luck number between a certain range
 */

#####GDescription
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.

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

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

#####R=== get_player_race_name ===

#####GDeclaration
    cptr get_player_race_name(int pr, int ps);

#####GFile
    util.c

#####GComment
(none)

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

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

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

#####R=== quit ===

#####GDeclaration
    void quit(cptr str);

#####GFile
    z-util.c

#####GComment
/*
 * 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.
 */

#####GDescription
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.

#####GParameters
> "str" is an error message or exit code.

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

#####R=== dump_hooks ===

#####GDeclaration
    void dump_hooks();

#####GFile
    plots.c

#####GComment
(none)

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

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

#####R=== add_hook_script ===

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

#####GFile
    plots.c

#####GComment
(none)

#####GDescription
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.

#####GParameters
> "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.

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

#####R=== del_hook_name ===

#####GDeclaration
    void del_hook_name(int h_idx, cptr name);

#####GFile
    plots.c

#####GComment
(none)

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

#####GParameters
> "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.

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

#####R=== pern_dofile ===

#####GDeclaration
    bool pern_dofile(char *file);

#####GFile
    script.c

#####GComment
(none)

#####GDescription
Parse the Lua script file "file".

#####GParameters
> "file" is the Lua script file to be parsed.

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

#####R=== intMod ===

#####GDeclaration
    s32b intMod(s32b a, s32b b);

#####GFile
    script.c

#####GComment
(none)

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

#####GParameters
> "a" is a number.
> "b" is a number.

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

#####R=== intAnd ===

#####GDeclaration
    s32b intAnd(s32b a, s32b b);

#####GFile
    script.c

#####GComment
(none)

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

#####GParameters
> "a" is a number.
> "b" is a number.

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

#####R=== intOr ===

#####GDeclaration
    s32b intOr(s32b a, s32b b);

#####GFile
    script.c

#####GComment
(none)

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

#####GParameters
> "a" is a number.
> "b" is a number.

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

#####R=== intXor ===

#####GDeclaration
    s32b intXor(s32b a, s32b b);

#####GFile
    script.c

#####GComment
(none)

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

#####GParameters
> "a" is a number.
> "b" is a number.

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

#####R=== intShiftl ===

#####GDeclaration
    s32b intShiftl(s32b a, s32b b);

#####GFile
    script.c

#####GComment
(none)

#####GDescription
Return the result of bitwise operation "a" << "b".

#####GParameters
> "a" is a number.
> "b" is a number.

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

#####R=== intShiftr ===

#####GDeclaration
    s32b intShiftr(s32b a, s32b b);

#####GFile
    script.c

#####GComment
(none)

#####GDescription
Return the result of bitwise operation "a" >> "b".

#####GParameters
> "a" is a number.
> "b" is a number.

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

#####R=== intBitNot ===

#####GDeclaration
    s32b intBitNot(s32b b);

#####GFile
    script.c

#####GComment
(none)

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

#####GParameters
> "b" is a number.

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

#####R=== register_savefile ===

#####GDeclaration
    void register_savefile(int num);

#####GFile
    loadsave.c

#####GComment
/*
 * Add num slots to the savefile
 */

#####GDescription
Add "num" slots to the save file.

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

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

#####R=== save_number_key ===

#####GDeclaration
    void save_number_key(char *key, s32b val);

#####GFile
    util.c

#####GComment
(none)

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

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

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



Back to the *****lua.hlp*0[lua help index] .


                                                     [[[[[gThis file by Chris Hadgis]