Difference between pages "Template:Function2" and "Data Types"

Revision as of 03:08, 2 March 2023

Primitive Datatypes

void

Can be thought of better as the absence of a datatype. No value can be assigned to void nor can a value be returned from a function of datatype void.

boolean

A boolean value is either true or false. By default, a boolean variable is set to false.

int

A whole number (short for "integer"), either positive or negative (or 0). The int used by KoLmafia is a 64-bit signed int, meaning it has a maximum value of 9,223,372,036,854,775,807 and a minimum value of -9,223,372,036,854,775,808. The default value of a integer variable is 0.

Be careful when doing math with integers! As with some other strongly-typed languages, numbers are converted to integers at every step of the operation when only integer types are used. For example:

int a = 1;
int b = 2;
print( a / b * 2 );

Will give the output "0," not "1" as you may expect. Changing either variable to a float type will "correct" this.

float

The float data type is a double-precision 64-bit IEEE 754 floating point. Its range of values is beyond the scope of this discussion, but is specified in section 4.2.3 of the Java Language Specification, and a tool to help understand / quickly see how/where imprecisions happen can be found here.

When assigning to a variable of type float, one should be careful to always enter numbers in decimal form, as unwanted behavior can result from supplying a value that KoLmafia may interpret as an int type without the decimal point.

Note that float is not infinitely precise; it intrinsically rounds off after a certain point. This loss of accuracy is for the sake of storage, but beware of the possibility of small errors compounding from multiple float types.

For instance, try the following code as an example of how rather long post-decimal portions are handled:

float f;
f = 4.9999999;
print( f );

The default value of a float variable is 0.0.

string

A group of characters including, but not limited to: lowercase letters, uppercase characters, numbers, and various control characters. When assigning a value to a string, enclose the desired value in either single quotes ('), double quotes (") or backticks (`) (note you must use the same quote type on both ends of the string assignment). If you need to include the same character inside of the string itself, you will need to escape it first with a backslash.

For example:

string s = "This is my \"friend\" Pete.";

Will result in the following being stored to s:

This is my "friend" Pete

The default value of a string is an empty string, or literally ""

When using backticks, you can concatenate expressions into your string using curly braces.

For example:

string s = `Hello {my_name()}, you have {$item[lime].item_amount()} lime(s)!`;

buffer

Similar to a string, but more efficient in certain operations, including concatenation and passing as function arguments. For the most part, you can interchange references to strings and buffers. However, you should test all such actions first, as a few functions require a specific datatype to be supplied as a parameter. (Most notably, those listed under Regular Expressions.)

Special Datatypes

Several datatypes are included in KoLmafia to represent common categories within the KoL universe.

Note that while variables of these types are declared in the same way as for Primitive Datatypes; assigning and referencing them is done differently.

For example, to declare an item datatype and assign it a value, you would use the following line of code:

item it = $item[ broken skull ];

The default values of any variable of one of the following types is $type[ none ]. For example, the default value of a item variable is $item[ none ].

bounty

These are the non-items that the bounty hunter asks you to retrieve from monsters around the kingdom. There are quite a lot of them (42 in total) so I won't list them all here. You can find more about bounties at the The Bounty Hunter Hunter's Shack.

class

Besides $class[ none ], there are six possible values for this datatype:

Seal Clubber
Turtle Tamer
Pastamancer
Sauceror
Disco Bandit
Accordion Thief

coinmaster

All shops that deal with currency other than meat. Known values include:

effect

Any effect you can be under in KoL, whether from items, skills, or what-have-you, is valid for this datatype.

The full range, besides $effect[ none ], is too much to list and keep up with here: please see the Wiki Effects page for more information.

element

Besides $element[ none ], there are seven possible values for this datatype. (Note that "Bad Spelling" is not considered a true element.) Also note that these names are case-sensitive (referencing $element[ Spooky ] will generate an error).

cold
hot
sleaze
spooky
stench
slime
supercold

familiar

Any familiar available in KoL is valid for this datatype.

The full range, besides $familiar[ none ], is too much to list and keep up with here: please see the Wiki Familiars page for more information.

item

Any item in all of KoL is valid for this datatype. Note that unlike most special datatypes, item references can make use of the item ID number.

For example, you could assign the item plexiglass pants as follows:

item it = $item[ 1234 ];

The full range, besides $item[ none ], is too much to list and keep up with here: please see the Wiki Items page for more information.

location

Any location one can adventure at in KoL is valid for this datatype.

The full range, besides $location[ none ], is too much to list and keep up with here: please see the Wiki Locations page for more information.

monster

Any monster you can encounter in KoL is valid for this datatype.

The full range, besides $monster[ none ], is too much to list and keep up with here: please see the Wiki Monster Compendium page for more information.

path

Any ascension path you can choose in Valhalla is valid for this datatype. This includes all special challenge paths, as well as Standard and the dietary restriction paths (Boozetafarian, Teetotaler, Oxygenarian). The "Unrestricted" path and aftercore are represented as $path[ none ].

The full range, besides $path[ none ], is too much to list and keep up with here. See Ascension#Paths for more information.

phylum

Each monster has a Phylum. Besides $phylum[none], the possible values for this datatype are:

beast
bug
constellation
construct
demon
dude
elemental
elf
fish
goblin
hippy
hobo
humanoid
horror
mer-kin
orc
penguin
pirate
plant
slime
undead
weird

servant

Servants are unique to the Actually Ed the Undying path and located The Servants' Quarters, replacing familiars.

Assassin
Belly-Dancer
Bodyguard
Cat
Maid
Priest
Scribe

skill

Any skill you can have in KoL, whether permable or not, granted by items, etc., is valid for this datatype.

The full range, besides $skill[ none ], is too much to list and keep up with here: please see the Wiki Skills page for more information.

slot

(Related Functions) (slot has no proxy record fields)

Besides $slot[ none ], there are 16 possible values for this datatype.

hat
back
weapon
off-hand
shirt
pants
acc1
acc2
acc3
familiar
sticker1
sticker2
sticker3
fakehand
bootspur
bootskin

stat

(Related Functions) (stat has no proxy record fields)

Besides $stat[ none ], there are six possible values for this datatype (the last three are for referencing sub-stats).

muscle
mysticality
moxie
submuscle
submysticality
submoxie

thrall

Pastamancers have the ability to summon Pasta Thralls.

Angel Hair Wisp
Elbow Macaroni
Lasagmbie
Penne Dreadful
Spaghetti Elemental
Spice Ghost
Vampieroghi
Vermincelli

aggregate

An aggregate is a complex datatype composed of two or more primitive or special datatypes. For more information, see Data Structures.

record

Records are user-defined datatypes that hold as many sub-datatypes as desired. For more information, see the page for Data Structures.

Plural Typed Constants

(see http://kolmafia.us/showthread.php?p=15592, from which this section is reproduced)

Plural typed constants allow you to easily do something with a list of specified objects, without having to replicate code or laboriously build up an array of the objects so that you can iterate over it. Here's a quick example:

foreach weapon in $items[star sword, star staff, star crossbow] {
   if (available_amount(weapon) > 0) {
      equip(weapon);
      break;
   }
}

The syntax is basically the same as the existing typed constant feature, but with an "s" or "es" after the type name. (The "es" case is there so that you can properly pluralize "class".) The text between the square brackets is interpreted as a comma-separated list of elements, each of which is converted to the specified type as if it were an individual constant. More details:

The list can span multiple lines.
Whitespace before or after elements is ignored.
Completely empty elements are ignored (so that you can leave a comma at the end of the list).
You can include a comma or closing square bracket in an element by writing it as "\," or "\]".
All the other escape sequences allowed in strings are possible, such as "\n" (newline), "\t" (tab), and "\uXXXX" (Unicode character value). To put an actual backslash in an element, you have to write it as "\\".

The value generated by a plural constant is of type boolean[type], with the keys being the specified elements, and the boolean value always being true - although you won't normally do anything with the boolean, you'd use a foreach loop to iterate over the keys. You can assign a plural constant to a variable declared as that type, but note that the value differs from a normal map in three important respects:

Since the expression that generates it is syntactically a constant, the value has to be immutable. If you were allowed to change it in any way, those changes would appear in every future use of the same constant.
There can be multiple instances of the same key - $ints[1,1,2,3,5,8] is perfectly valid, and will result in the value 1 appearing twice in a foreach loop.
The keys will appear in the order you wrote them, rather than being sorted alphanumerically as maps usually do.

In addition to being used in a foreach loop, plural constants also efficiently support membership testing via the 'contains' operator. Here's another example:

for hour from 1 to 12 {
   print("It's " + hour + " o'clock.");
   if ($ints[10, 2, 4] contains hour) {
      print("Time to drink a Dr Pepper!");
   }
}

(Yes, that example could just as easily have been done with a switch statement.)

Iterating over an empty list is rather pointless, so plural constants with no elements are given a different meaning: they represent every value of the specified type, where this is practical. (The 'none' value, if defined for a given type, is omitted.) The biggest benefit here is $items[], which lets you loop over every defined item, more efficiently than you could otherwise write in a script (since the list is generated once per session and then cached), and without having to hard-code a maximum item ID number in your script. Example:

foreach it in $items[] {
   if (autosell_price(it) == 42) print(it);
}

Enumeration of all possible values works with the following types:

$booleans[] - false and true.
$items[]
$locations[]
$classes[]
$stats[] - Muscle, Mysticality, Moxie: the substat values are omitted.
$skills[]
$effects[]
$familiars[]
$slots[] - includes sticker slots and fake hands, which you might not want to consider as normal slots.
$monsters[]
$elements[] - includes slime now, and possibly other not-quite-elements like cute in the future.

The remaining types that can be used in plural constants require an explicit list of elements, since there are too many possible values:

$ints[] - you don't have enough RAM to store a list with 4 billion elements.
$floats[] - ditto.
$strings[] - nobody has that much RAM.

Custom

matcher

A matcher isn't really a datatype so much as it's a class, but it is included here for reference, as it is used much as datatypes are in ASH. It can only be declared through the function create_matcher(), using two strings. One is the string to find matches in, the other a regular expression to test against. For more information on using a matcher, see Regular Expressions.

Notes

Buffers, aggregates, records and matchers are mutable. All other datatypes are immutable.