[Package Index | Mudlib Index | Effect Index]

File /obj/handlers/money_handler.c

This handles all the methods for determining values of coins and the current valid set of coins. It also handles change calculation. This was written originaly by Pinkfish, reworked significantly by Deutha to add in the multiple currency areas.

See also:
/std/living/money.c

Written by Pinkfish

Includes

This class includes the following files /include/shops/bank.h and /include/money.h

Method index

Public Functions

These are functions that everyone can access.

add_details
void add_details(string type,
string head_short,
string tail_short,
string head_long,
string tail_long,
mixed composition,
string plural,
string singular)

This method adds the details for the given coin type into the current list.

Parameters:
type - the coin type the details are for
head_short - the heads side short
tl_sht - the tail side short
hd_lng - the head side long
tl_lnd - the tail side long
composition - the composition of the money
plural - the plural value of the object, if 0 then use default plural. The default plural is "coins", and the default main plural is " coins", so in general you should always set the plural.
singular - the singlar value of the object, if 0 then use default singular. The default singular is the last word of the 'type' parameter, and the default main singular is the 'type' parameter

See also:
query_details_for() and remove_details()


add_place_alias
int add_place_alias(string name,
string alias)

This method adds a place alias.

Returns:
1 if successful, 0 otherwise


add_symbol
void add_symbol(string word,
string symboliser)

This method adds in a symboliser for a specified money area.

Parameters:
word - the money area to add the symbol for
symboliser - the path to the symboliser object

See also:
query_symbols(), query_symbol_for() and remove_symbol()

Example: 
add_symbol("Ankh-Morpork", "/d/am/money");

// This is an example of a symboliser object
string symbolise_value(int value)
{
   int dollars;
   int pence;

   dollars = value / 400;
   pence = (value % 400) / 4;
   if (pence == 0) {
       return "A$" + dollars;
   }

   if (dollars == 0) {
       return pence + "p";
   }

   if (pence < 10) {
       return "A$"+ dollars + ".0" + pence;
   }

   return "A$" + dollars + "." + pence;
} /* symbolise_value() */

add_type
void add_type(string where,
string type,
int value)

This adds a type of money to the money handler.

Parameters:
where - the area in which to add the type of money
type - the name of the money to add
value - the value of the money

See also:
query_values_in() and remove_type()


calc_change
mixed * calc_change(int value,
mixed * mon_array)

This method calculates the change of a certain value from a given money array. This makes sure that the change does not include money that does not actually exist.

Parameters:
value - the value of the change to calculate
mon_array - the money array to determine the change from

Returns:
the money array containing the change to use

See also:
make_payment() and pay_amount_from()


clear_place_short
void clear_place_short(string place)

Remove the special short for a place
create_money_array
varargs mixed * create_money_array(int value,
string where)

This method creates a money array from a certain value in a particular money area. A money array consists of ({ type, number }) pairs in an array, ie: ({ "brass", 12, "copper", 24 }).

Parameters:
value - the value to get the money array for
where - the money area to get the value in

Returns:
a money array for the value in the area

See also:
money_value_string()

Example: 
place = query_property("place");
if (!place) {
     place = "default";
}
mon_array = create_money_array( 1000, place);

dump_money_ob
void dump_money_ob(object ob)
filter_legal_money_array
varargs object * filter_legal_money_array(mixed * m_array,
string where)

This method is identical to filter_legal_tender, except that it takes a money array rather than a money object

Parameters:
m_array - the money array to get the legal tender from
where - the money area the tender is for

Returns:
an two element array of objects ({ legal, illegal })

See also:
parse_money(), filter_legal_tender() and filter_legal_money_to_array();


filter_legal_money_to_array
varargs mixed * filter_legal_money_to_array(mixed * m_array,
string where)

This method is identical to filter_legal_money_array, except that it returns an array of two money arrays rather than an array of two money objects

Parameters:
m_array - the money array to get the legal tender from
where - the money area the tender is for

Returns:
an two element array of money arrays ({ legal, illegal })

See also:
parse_money(), filter_legal_tender() and filter_legal_money_array()


filter_legal_tender
varargs object * filter_legal_tender(object money,
string where)

This method figures out the legal and illegal tender money from the specified money object in the specified money area. This method returns a two element array which consists of the legal and illegal tender for the given money area ({ legal, illegal }). WARNING: This method destructs the money object passed to it.

Parameters:
money - the money object to get the legal tender from
where - the money area the tender is for

Returns:
an two element array of objects ({ legal, illegal })

See also:
parse_money(), filter_legal_money_array() and filter_legal_money_to_array()


get_money_ob
object get_money_ob()
make_money_array_payment
mixed * make_money_array_payment(string type,
int value,
mixed * mon_array,
string where,
int use_default)

This method makes a payment from a money array. It returns the depleted money array, the amount taken out and the change needed. If the type is not set, then the best fit for the value is found from the array.

The return array is formated as:
({ depleted_money_array, change, taken_from })
The change is an integer value.

Parameters:
type - the type of money to take out (ie: "Lancre Crown")
value - the amount of the type to take out
mon_array - the money array to use
where - the money area
use_default - allow the use of the default money type

Returns:
the return array as formated above

Example: 
ret = make_money_array_payment("Lancre Crown", 2, mon_array, "Lancre", 0);

make_new_amount
varargs object make_new_amount(int value,
string where)

This method creates a money object of a certain value in a certain money area.

Parameters:
value - the value to create the new money object with
where - the area to create the new money object in

Returns:
the new money object


make_payment
varargs mixed * make_payment(string type,
int value,
object ob,
string where)

This method makes a payment of a particular amount in a particular money area. Please note that player or living objects can double as money objects in this circumstance. The first element of the payment array is the values which should be used to take off the player, the second element is the change needed to be payed back.

Parameters:
type - the type of money to pay in (ie: "Lancre Crown")
value - the number of the type to pay
ob - the thing which is doing the payment (money object)
where - the money area the payment will occur in

Returns:
the payment array

See also:
pay_amount_from() and calc_change()


make_value_payment
mixed * make_value_payment(int value,
mixed * marr,
string place)
merge_money_arrays
mixed * merge_money_arrays(mixed * m_array1,
mixed * m_array2)

This method merges two money arrays together and returns the merged array

Parameters:
m_array1 - the first money array
m_array2 - the second money_array

Returns:
a money array of m_array1 and m_array2 joined


money_array_from_string
mixed * money_array_from_string(string str,
string where)

This method attempts to find a money value from a string. It will attempt to do fuzzy matching of the type. This means it will match on partial matches, this could lead to somewhat weird behaviour... So it goes... It will return a money array, rather than a value

Parameters:
str - the string to find the value of

Returns:
a money array of the types matched

See also:
money_value_string()


money_string
string money_string(mixed mon_array)

This method converts a money array into a string so it can be displayed.

Parameters:
mon_array - the money array to convert into a string

Returns:
the verbose string for all the denominations in the array

See also:
money_value_string() money_symbol_string()


money_symbol_string
string money_symbol_string(mixed * mon_array)

This method converts a money array into a symbolic string so it can be displayed.

Parameters:
mon_array - the money array to convert into a string

Returns:
the symbolic string for the array

See also:
money_value_string() money_string()


money_value_string
varargs string money_value_string(int val,
string where)

This method returns a string which is based on the value of the money in a certain money area.

Parameters:
val - the value to get the string for
where - the place to get the string for

Returns:
a string of the money value in the certain money area

See also:
create_money_array(), money_string() and value_from_string()


parse_money
varargs mixed parse_money(string words,
object player,
string place)

This method determines all the money from the player object and moves it into a container. It then figures out the legal tender for specified money area and tells the player if the given money is legal tender for the current area. It will automatically return the illegal tender and send a message to the player about it.

Parameters:
words - the string to match the money on
player - the player who is attempting the transaction
place - the money area the transaction is taking place

Returns:
a money object consisting of the legal tender

See also:
filter_legal_tender()


pay_amount_from
varargs object pay_amount_from(int value,
object money,
string where)

This method makes a payment from a specified money object.

Parameters:
value - the amount to pay
money - the money object to pay from
where - the money area the payment occurs in

Returns:
the change object

See also:
make_payment() and calc_change()


query_adjectives_for
string * query_adjectives_for(string type)

This method returns all the current adjectives for the given type of money.

Parameters:
type - the type of money to get the adjectives for

Returns:
the adjectives for the money type

See also:
set_adjectives_for()


query_aliases_for
string * query_aliases_for(string type)

This method returns all the current aliases for the given type of money.

Parameters:
type - the type of money to get the aliases for

Returns:
the aliases for the money type

See also:
set_aliases_for()


query_aliases_for_place
string * query_aliases_for_place(string name)

This method returns an array containing all the place aliases for a given place.

Returns:
place aliases


query_aliases_of
string * query_aliases_of(string word)

This converts a currency type's alias (i.e. "royal") and returns its 'real' names (i.e. "Ankh-Morpork royal")

Parameters:
word - the alias to find the real name of

Returns:
an array of real names, or 0 if it's not a real alias


query_all_places
string * query_all_places()

This method returns the current set of areas in which types can be found.

Returns:
the set of places


query_all_values
mapping query_all_values()

This method returns the mapping containing all the values of the currently valid money types. The mapping has keys of the domain of the money and has a value of an array. The array contains alternating name, value pairs. 
([ "default": ({ "brass", 1, "copper", 10, "silver", 100, "gold", 2000, "platinum", 6000 }) ])


Returns:
the mapping of values

See also:
query_values() and query_values_in()


query_details
mapping query_details()

This method returns all the details for the current set of coins. The details are information which is shown when the coin is looked at. Stuff about heads and tails and things. 
  ([
     "brass": ({ "heads", "tails", "a head", "a tail", "brass", 0, 0 }),
     "copper": ({ "heads", "tails", "a head", "a tail", "copper", 0, 0 }),
     "silver": ({ "heads", "tails", "a head", "a tail", "silver", 0, 0 }),
     "gold": ({ "heads", "tails", "a head", "a tail", "gold", 0, 0 }),
     "platinum": ({ "heads", "tails", "a head", "a tail", "platinum", 0, 0 })
  ])
The places correspond to: 
({ heads short, tails short, heads long, tails long, composition, plural, singular })


Returns:
the details array


query_details_for
mixed * query_details_for(string word)

This method returns the details for a specified type of money. It will return an array of the form: 
({ "heads", "tails", "a head", "a tail", "brass", 0, 0 })
The places correspond to: 
({ heads short, tails short, heads long, tails long, composition, plural, singular })


Parameters:
word - the money type to get the type for

See also:
add_details()


query_main_plural_for
string query_main_plural_for(string type)

This method returns the main plural description of the money type. This returns the expanded plural version like 'Ankh-Morpork pence'.

Parameters:
type - the money type to get the plural description for

Returns:
the full plural description for the money object

See also:
set_plural_for(), query_plural_for() and query_short_for()


query_main_singular_for
string query_main_singular_for(string type)

This method returns the main singular description of the money type. This returns the expanded singular version like 'Ankh-Morpork penny'.

Parameters:
type - the money type to get the singular description for

Returns:
the full singular description for the money object

See also:
set_singular_for(), query_singular_for() and query_short_for()


query_mapped_values_in
mapping query_mapped_values_in(string where)

This method returns the values in the specified area. It contains name, value pairs and is for the "default" area. It is returned as a mapping for easier sorting & manipulation.

Parameters:
where - the area in which to return the values for

See also:
query_all_values(), query_values(), add_type() and query_values_in()


query_number_coins
int query_number_coins(mixed * money_array)

This method returns the number of coins in the object.

Parameters:
money_array - The money array to count

Returns:
the number of coins


query_origin_of
string query_origin_of(string type)

This takes a coin type and returns the place it is associated with.

Parameters:
type - the coin type i.e. "Ankh-Morpork dollar"

Returns:
the place i.e. "Ankh-Morpork"


query_person_payments
mixed * query_person_payments(int value,
string place,
object payer,
object payee)

This method makes a payment from one person to another. This method figures out what money should be given to the player and what should be taken from the other to make a payment of the correct value in the correct place.

Parameters:
value - the value to pay
place - the place to make the payment in
payer - the person the money is payed from
payee - the person the money is payed to

Returns:
two element array, or 0 if it cannot be done


query_place_aliases
mapping query_place_aliases()

This method returns the mapping containing all the place aliases.

Returns:
place aliases


query_place_from_alias
string query_place_from_alias(string name)

This method returns the place for a given place alias.

Returns:
place


query_place_prefix
string query_place_prefix(string place)
query_place_short
string query_place_short(string place)

Get the short for a place

Returns:
The special short for the place, or the place argument if there is no special short


query_plural_for
string query_plural_for(string type)

This method returns the short plural description of the money type. This returns just the one word, like 'coins' or 'talons'.

Parameters:
type - the money type to get the short plural description for

Returns:
the short plural description for the money object

See also:
set_plural_for() and query_main_plural_for()


query_short_desc
string query_short_desc(mixed * marr,
int full)
query_short_for
string query_short_for(string type)

This method returns the short description of the money type.

Parameters:
type - the money type to get the short description for

Returns:
the short description for the money object

See also:
query_main_plural_for()


query_shorts
string * query_shorts(mixed * marr,
int full)
query_shorts_from_proxy_data
string * query_shorts_from_proxy_data(class money_proxy_data * data,
int full)
query_singular_for
string query_singular_for(string type)

This method returns the short singular description of the money type. This returns just the one word, like 'coin' or 'talon'.

Parameters:
type - the money type to get the short singular description for

Returns:
the short singular description for the money object

See also:
set_singular_for() and query_main_singular_for()


query_smallest_value_in
int query_smallest_value_in(string where)

This returns the smallest value in the specified area. Used to make sure we are not charging too little or too much when doing comparisons.

Parameters:
where - the area to check

Returns:
the smallest value in the specified area


query_symbol_for
string query_symbol_for(string word)

This method returns the symboliser for the specified money area.

Parameters:
word - the area in which the money is occuring

Returns:
the syboliser for the money area

See also:
query_symbols(), add_symbol() and remove_symbol()


query_symbols
mapping query_symbols()

This method returns all the symbols for the current money areas in the handler. The return value is mapping with the key being the money area and the value being the symboliser for the money. The symboliser is called with a value to get the money to print itself out nicely. This is used when the quantity of actual coins is not known and only the value of them is known.

Returns:
all of the symbols

See also:
query_symbol_for(), add_symbol() and remove_symbol()


query_total_value
varargs int query_total_value(mixed * mon_array,
string where)

This method determines the total value of a specified money array. A money array consists of pairs of values ({ type, number })

Parameters:
mon_array - the array to find the value of
where - the money area to get the value in

Returns:
the total value as an integer

See also:
query_value()


query_valid_place
int query_valid_place(string where)

This method checks if a string is a valid currency area

Returns:
1 if true, 0 if not.

See also:
query_all_places()


query_valid_types
string * query_valid_types()

This returns a list of valid coin types

Returns:
an array of valid coin types


query_value
varargs int query_value(string type,
string where)

This method returns the value of a specified type of money in a certain money area.

Parameters:
type - the type of money to get the value for
where - the money area the money is in

Returns:
the integer value of the money

See also:
query_total_value()


query_value_of
int query_value_of(string type)

This returns the value of a currency type.

Parameters:
type - currency type

Returns:
an int of the currency type's value


query_values
mixed * query_values()

This method returns the values in the default area. This method returns the array as given in the value above. It contains name, value pairs and is for the "default" area.

Returns:
the array of values

See also:
query_all_values() and query_values_in()


query_values_in
mixed * query_values_in(string where)

This method returns the values in the specified area. It contains name, value pairs and is for the "default" area.

Parameters:
where - the area in which to return the values for

Returns:
the array of values

See also:
query_all_values(), query_values(), add_type() and query_mapped_values_in()


query_weighted_values_in
mixed * query_weighted_values_in(string where,
int backwards)
remove_details
void remove_details(string type)

This method removes the specified detail.

Parameters:
type - the type of money to remove the details for

See also:
add_details() and query_details_for()


remove_symbol
void remove_symbol(string word)

This method removes the symboliser for the particular money area.

Parameters:
word - the money area to remove the symbol for

See also:
query_symbols(), query_symbol_for() and add_symbol()


remove_type
void remove_type(string where,
string type)

This method removes the type of money from the handler.

Parameters:
where - the area to remove it from
type - the type to remove

See also:
add_type()


reset_cache
void reset_cache()
save_me
void save_me()

This method saves the current state of the money object.
set_adjectives_for
void set_adjectives_for(string type,
string * words)

This method sets the adjectives for the specified money type.

Parameters:
type - the type of money to set the adjectives for
words - the adjectives for the money
type - the type of money to set the adjectives for
words - the adjectives for the money

See also:
query_adjectives_for()


set_aliases_for
void set_aliases_for(string type,
string * words)

This method sets the aliases for the specified money type.

Parameters:
type - the type of money to set the aliases for
words - the aliases for the money
type - the type of money to set the aliases for
words - the aliases for the money

See also:
query_aliases_for()


set_place_short
int set_place_short(string place,
string short)

Sets the short for a place if it needs something special. This is the string that would be used to complete the phrase "This coin is from ....". For example, "Ankh-Morpork" doesn't need anything special, so doesn't need a place short, but "Counterweight Continent" should be shown as "the Counterweight Continent".

Returns:
1 if successful, 0 otherwise


set_plural_for
void set_plural_for(string type,
string plural)

This method sets the plural for the specified money type.

Parameters:
type - the money to set the plural for
plural - the new plural for the money

See also:
query_plural_for() and query_main_plural_for()


set_singular_for
void set_singular_for(string type,
string singular)

This method sets the singular for the specified money type.

Parameters:
type - the money to set the plural for
singular - the new singular for the money

See also:
query_short_for()


smallest_in
string smallest_in(string place)

This returns the smallest unit of currency in this place.

Parameters:
place - The place to query.

Returns:
A string of the smallest unit of currency

See also:
smallest_value_in()


smallest_value_in
int smallest_value_in(string place)

This returns the smallest value of currency in this place.

Parameters:
place - The place to query.

Returns:
the value of the smallest unit of currency

See also:
smallest_in()


sort_money_array
mixed * sort_money_array(mixed * marr)
sort_money_array_by
varargs mixed * sort_money_array_by(mixed * marr,
function f,
int backwards)
string_to_money_array
mixed * string_to_money_array(string str,
string * places,
mapping ref ambiguous,
string ref * unknown)

This function attempts to parse a string of money designations (eg, "10 AM dollars"). Multiple designations may be separated by comma and a space (both required). Symbolised designations (eg, A$10) are accepted.

Parameters:
str - The string to parse
places - The places to search
ambiguous - (out) If any parts of the input string could match multiple money types, the keys in this mapping will be the ambiguous string from the input, and the value for each key will be an array of size 2, where the first element is an array of all the possible choices, and the second element is the total amount of the ambiguous type
unknown - (out) This array will contain any parts of the input string that didn't match any money type or were not in a recognized format

Returns:
The total money array of all the parts in the input string that matched a money type

Example: 
mapping  ambiguous;
mixed   *total_money_array;
string  *unknown;

total_money_array = string_to_money_array("A$1.20, 20 rubbish, 5 talents, a hedgehog",
                                          ({ "Ankh-Morpork", "Djelibeybi", "Tsort", "Lancre" }),
                                          ref ambiguous,
                                          ref unknown);
printf("%O\n", total_money_array);
printf("%O\n", ambiguous);
printf("%O\n", unknown);

Results in:
({ // sizeof() == 6
  "Ankh-Morpork dollar",
  1,
  "Ankh-Morpork ten-pence",
  2,
  "Lancre hedgehog",
  1
})
([ // sizeof() == 1
  "talents" : ({ // sizeof() == 2
      ({ // sizeof() == 2
         "Djelian talent",
         "Tsortean talent"
      })
      5,
  }),
])
({ // sizeof() == 1
  "rubbish"
})

value_from_string
int value_from_string(string str,
string where)

This method attempts to find a money value from a string. It will attempt to do fuzzy matching of the type. This means it will match on partial matches, this could lead to somewhat weird behaviour... So it goes...

Parameters:
str - the string to find the value of

See also:
money_value_string()

Example: 
// This will tell us the integer money value of the string.
write(MONEY_HAND->value_from_string("1 dollar and 12 pence", "Ankh-Morpork"));