View source for Zlib

{{TOCright}}{{DISPLAYTITLE:ZLib (zlib.ash)}}
== About Zarqon's Useful Function Library ==
Behold, a single function library containing most of zarqon's most useful functions, which will be used by most of his scripts. He grew tired of tweaking a function that was in multiple scripts and making sure he had changed them all. ''It would be nice'', he thought in his customary italics, ''to have it in just one place''.

In choosing which functions to include, he have tried to select only those functions which are a) super useful, or 2) needed by another of the included functions. It's a bit less efficient in terms of individual scripts, but in terms of repeated code across a family of scripts it is far simpler.

== Functions ==

{{HideLink|excise}}{{Function|
name=excise|
return_type=string|
parameter1={{Param|string|source}}|
parameter2={{Param|string|start}}|
parameter3={{Param|string|end}}|
p1desc=The original {{pspan|source}} string|
p2desc={{pspan|start}} after this string|
p3desc={{pspan|end}} before this string|
}}
This function returns a portion of the {{pspan|source}} string, from after the first occurrence of {{pspan|start}} to just before the first occurrence of {{pspan|end}}. If either {{pspan|start}} or {{pspan|end}} are missing, it will return an empty string. You can also supply either {{pspan|start}} or {{pspan|end}} as blank strings to specify the actual start or end of the {{pspan|source}} string.

{{HideLink|normalized}}{{Function|
name=normalized|
return_type=string|
parameter1={{Param|string|mixvar}}|
parameter2={{Param|string|type}}|
p1desc={{pspan|mixvar}} is the string to normalize|
p2desc={{pspan|type}} is the datatype to normalize to|
}}
Returns {{pspan|mixvar}}, normalized to the specified mafia {{pspan|type}}, which can be any primitive type or ASH datatype constant. For example, normalized("badger", "familiar") would return "Astral Badger".

{{HideLink|rnum}}{{Function|
name=rnum|
return_type=string|
parameter1={{Param|int|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
}}
{{Function|
name=rnum|
return_type=string|
parameter1={{Param|float|n}}|
parameter2={{Param|int|place}}|
p1desc={{pspan|n}} is a number|
p2desc={{pspan|place}} is the number of decimal places to round to|
}}
Returns your number {{pspan|n}} as a human-readable string. For ints, this means it adds commas where appropriate. For floats, it also rounds to the nearest {{pspan|place}} after the decimal. Default {{pspan|place}} for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string().

{{HideLink|set_avg}}{{Function|
name=set_avg|
return_type=void|
parameter1={{Param|float|to_add}}|
parameter2={{Param|string|which_prop}}|
p1desc={{pspan|to_add}} is the data point to add|
p2desc={{pspan|which_prop}} is the property to add data to|
}}
Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this script three times with the values 2, 4, and 6 for {{pspan|to_add}} would result in the property {{pspan|which_prop}} containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

{{HideLink|get_avg}}{{Function|
name=get_avg|
return_type=float|
parameter1={{Param|string|which_prop}}|
p1desc={{pspan|which_prop}} is the property to access|
}}
Returns an average value set by set_avg().

{{HideLink|eval}}{{Function|
name=eval|
return_type=vfloat|
parameter1={{Param|string|expression}}|
parameter2={{Param|float [string]|values|ag=t}}|
p1desc={{pspan|expression}} is the base expression|
p2desc={{pspan|values}} is a map of values to replace|
}}
By Jason Harper. Evaluates {{pspan|expression}} as a math expression, and allows you to substitute {{pspan|values}} for variables, as described in much greater detail here. A brief version of this documentation is also included in ZLib. (NB: This section needs more infoz.)

{{HideLink|vprint}}{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
}}
{{Function|
name=vprint|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
parameter3={{Param|int|level}}|
p1desc={{pspan|message}} and {{pspan|color}} are used as in the function {{f|print}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Wrapper for print() and abort(), prints message depending on vars["verbosity"] setting. It has a boolean return value so it can replace { print(message); return t/f; }
if level == 0: abort with message
if level > 0: prints message if verbosity >= level, returns true
if level < 0: prints message if verbosity >= abs(level), returns false

First, level controls the return value -- if level is positive, vprint will return true; if negative, it will return false. If level is 0, vprint() will abort with the specified message. You can see now that vprint already replaces both abort() and error(). I recommend using it in place of abort() in case a savvy user wishes to avoid or otherwise handle aborts somehow.

So this takes care of my annoyance with needing brackets and two commands just to return a boolean along with user feedback. How about the verbosity issue?

Ladies and gentlement, there is now a new ZLib setting "verbosity" (integer). If the absolute value of level is more than verbosity, the message will not be printed. This allows users to control the chattiness of scripts, and allows authors to include debug print statements which can be shown by setting verbosity high.

'''Recommendations for Verbosity Levels in vprint()'''

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"


This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

There is also a version of vprint() without the color parameter. The default color is black for positive values of level, and red for negative values. So, basically you don't need to use the version with color unless you want to specify a different color or override the default colors.

{{HideLink|vprint_html}}{{Function|
name=vprint_html|
return_type=boolean|
parameter1={{Param|string|message}}|
parameter2={{Param|int|level}}|
p1desc={{pspan|message}} is used as in the function {{f|print_html}}|
p2desc={{pspan|level}} is a verbosity reference|
}}
Same as vprint() above, but wraps {{f|print_html}}.

{{HideLink|abs}}{{Function|
name=abs|
return_type=int|
parameter1={{Param|int|n}}|
}}
{{Function|
name=abs|
return_type=float|
parameter1={{Param|float|n}}|
p1desc={{pspan|n}} is a number of either int or float type.|
}}
Returns the absolute value of the number {{pspan|n}} in the same datatype as supplied.

{{HideLink|minmax}}{{Function|
name=minmax|
return_type=float|
parameter1={{Param|float|a}}|
parameter2={{Param|float|min}}|
parameter3={{Param|float|max}}|
p1desc={{pspan|a}} is the original number|
p2desc={{pspan|min}} is the minimum return value|
p3desc={{pspan|max}} is the maximum return value|
}}
Returns {{pspan|a}}, but no less than {{pspan|min}} and no more than {{pspan|max}}.

string check_version(string soft, string prop, string thisver, int thread)
Server-friendly once-daily version-checking. (Also hyphen-friendly.) If the user hasn't checked yet today, visits the specified thread in this forum to find the current version of your script. The thread must include "<b>soft version</b>" for the version info to be successfully parsed. Optionally, you may include "[requires revision XXXX]" in the post if you want to indicate a required minimum revision of mafia. If a new version is available, alerts the user in large text and provides an update link, then waits for a sufficiently annoying interval in case the user wishes to abort operation to go update the script. The return value is a blank string unless an update is found, in which case it is a <div id='versioninfo'> containing the update message. This allows this function to work equally well for relay scripts. The current version is stored to a daily property, standardized to "_version_"+prop. Example:
Code:

check_version("Hardcore Checklist","checklist","1.2.7",1045);

boolean load_current_map(string fname, aggregate dest)
Allows scripts to automatically update data files. Loads a map named fname.txt, either from disk or from the Map Manager if an update is available. (Yes, this means you shouldn't include ".txt" in the parameter.) The first time you try to load a given map on a given day, it checks if your version is current. If so, it merely loads it from disk. If not, it overwrites your local map with the map stored on the Map Manager.

int setvar(string varname, mixed dfault)
Allows you to define a per-character script setting to be used across all scripts that use ZLib. The first time the script is run, the variable will be set to dfault. To reference this setting, use vars[varname] in any script that includes ZLib, keeping in mind that this will always be a string. Detailed information posted here.

int have_item(string tolookup)
A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped.

float has_goal(item whatsit)
Returns the chance that an item is or results in a goal. If is_goal(item) == true or it's a bounty item, returns 1.0. Otherwise, returns the chance that you would get a goal from using the item. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58. Many thanks to aqualectrix for creating and sharing the container items results map.

float has_goal(monster m)
Making use of the above function, returns the percent chance that encountering a given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

float has_goal(location l)
Returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

boolean obtain(int n, string cond, location locale)
Attempts to get n (-existing) of cond, either by purchasing (if you have the mafia preference set), pulling from Hangk's, or adventuring at locale. It also works with choiceadvs.

boolean use_upto(int n, item doodad, boolean purchase)
Gets (if purchase is true) and uses n doodads if possible. Otherwise, uses as many as you have up to n.

boolean resist(element req, boolean reallydoit)
Returns whether you are able to resist a given element, or if reallydoit is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot), and returns its success.

int my_defstat()
Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

int get_safemox(location wear)
Using mafia's location/monster data, returns the safe moxie of a given zone.

boolean auto_mcd(int safemox)
boolean auto_mcd(monster mob)
boolean auto_mcd(location place)
If your automcd setting is true, automatically adjusts your mind-control device for maximum stat gains based on safemox (or the safe moxie for place or mob) and your threshold setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats.

familiar best_fam(string ftype)
Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your is_100_run setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

boolean send_gift(string to, string message, int meat, int[item] goodies, string insidenote)
boolean send_gift(string to, string message, int meat, int[item] goodies)
Self-explanatory, really. Sends a gift to a player, able to split large amounts of items, useful return value.

boolean kmail(string to, string message, int meat, int[item] goodies, string insidenote)
boolean kmail(string to, string message, int meat, int[item] goodies)
boolean kmail(string to, string message, int meat)
Sends a kmail to a player, returning true if the kmail is successfully sent. Handles splitting the message into multiple messages if the number of item types is too large. Returns the result of send_gift() if the intended recipient is unable to receive the message due to being in HC or somesuch. Note that you can also specify the message to be used inside gifts in that case. Use "\n" to specify a new line in the message.

== Making use of Zlib ==
To include this library in your script, simply add the following towards the top of your script:
{{CodeSample|
code=
<syntaxhighlight>
import "zlib.ash";
</syntaxhighlight>}}
Then all these functions will be available in your script. Have fun!

== More Information ==
<p>See the thread for ZLib on the mafia forum [http://kolmafia.us/showthread.php?2072 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]