OBJECTS
/obj/money.c
/obj/money_demon.c
/lib/money.c
SYNOPSIS
#include <money.h>
inherit MONEY_LIB;
--
ob = clone_object(MONEY);
--
money = MONEY_DEMON->CreateMoney(1000,({"copper","gold"}));
--
DESCRIPTION
The three files do different tasks in the money system of OSB.
The money a player carries around is stored in an object instance
of MONEY.
The handling of the different currencies, their values and weights
is done by the MONEY_DEMON.
Objects that are designed to deal with the money find a lot of
useful functions in MONEY_LIB.
First the functions of special interest in MONEY:
public int id(string str)
This function is called by the gamedriver while evaluating the
present() efun.
But it can happen that str means only a part of the money.
In this case the money splits into two parts, the one meant by
str and the other containing the remainings of the money.
The other part stays outside the current environment for a while,
so you can work with the part meant by str. The other money
moves into the current environment of the money later.
public varargs mapping SetMoney(mixed amount, string type)
This function is used to initalise the money.
It erases the old value and sets the new value according to
the arguments.
amount can be either an integer (then type has to be a string
meaning a valid currency), then the money contains amount coins
of type.
Or amount is a money mapping, consisting of strings as indices
and integers as values.
Or amount can be an oldstyled money array. Then it got converted
internally to a money mapping.
In both cases type doesn't need to be set, it's ignored then.
public varargs int AdjustMoney(mixed amount, string type)
This function takes the same arguments as SetMoney().
But the given values are added to the stored ones rather than
overwriting them.
public mapping QueryMoney()
This returns the money mapping containing the money's values.
It looks typically like this:
(["gold":20,"silver":15,"copper":7])
public mapping QueryMoneyMap()
This function is no longer supported, because QueryMoney() now
does the job.
public mixed MakeArray(mapping money)
converts a money mapping into an oldstyled money array.
public mapping MakeMapping(mixed array)
converts a money array into a mapping.
Now the functions inside the MONEY_DEMON
public mapping QueryMaterials()
returns a list of predefined materials and their relative value.
public mixed QueryCoinTypes(void|string domain)
returns the setting of the differend currencies (cointypes), if
called without argument. If argument is a domain's uid, it returns
the valid coin types for this domain as an array of strings.
public string *QueryStandard()
returns the default cointypes (currently "platinum", "gold",
"silver" and "copper").
public int QueryMaterialValue(string material, int weight)
returns the value of weight grams of material.
public int QueryCoinValue(string type)
returns the value of the given coin type.
public mapping CleanMoney(mixed money)
erases all coin types with empty amount in money.
money can be either a money mapping or an oldstyled money array.
The resulting money mapping is returned.
public int QueryCoinWeight(string type)
returns the weight of a single coin of the given type.
public varargs int QueryMoneyValue(mixed money, string *types)
returns the value of the given money. Money can be either a
mapping or an array. If there is a list of types given too,
only the value of the coins of the given type is taken.
public int QueryMoneyWeight(mixed money)
returns the weight of the given money. Money can be either
a money mapping or a money array.
public int QueryCoinNumber(mixed money)
returns the amount of coins in money. The money can be either
a money mapping or a money array.
public varargs string QueryMoneyString(mixed money, int flag)
returns a short description for the given money. money can
be either a money mapping or a money array.
If flag is not zero, all numbers greater than flag are converted
to 'some' resp. 'lots of'.
public varargs string QueryMoneyShort(mixed money, int flag)
returns a shortened version of QueryMoneyString(), the currencies
show up with their abbreviation. Arguments are like
QueryMoneyString()
public varargs string QueryMoneyLong(mixed money, int flag)
returns a long description for the given money. money can
be either a money mapping or a money array.
If flag is not zero, all numbers greater than flag are converted
to 'some' resp. 'lots of'.
If there is only one coin type given in the money, the special
description of the coin type is returned.
public varargs mapping CreateMoney(int value, string *types)
creates a money mapping of the given value. If there is a list
of coin types given, the money will contains only coins of the
given types. Only if the value isn't representable by the given
types, "copper" is added automatically to the list.
If no types are given, the standards are used.
public varargs string QueryValueString(int value, string *types)
creates a string which is the description of a money object
with the given value. It contains only of coins of the given
types (or the standard coins), eventually copper coins are
added, if the value isn't representable by the given types.
public varargs mixed PayValue(int value, mixed money, string *types)
This function tries to pay a given value with the coins of
the given money, or, if types are specified, with the coins of
the given types out of the given money.
It returns 3 mappings:
The first one is the new money mapping,
the second one is the money you've to give away and
the third one is the change you get back.
The third value may be 0, if you don't get any change.
The function returns 0, if the paying couldn't be done.
public mapping PayMoney(mixed money, mixed to_pay)
tries to subtract the to_pay from money. Both money and
to_pay can be either a money mapping or an array.
It returns either the new money or 0, if the paying couldn't be done.
These functions are almost needed by MONEY to evaluate the
argument to id()
public string PresentMoney(string type, mixed money)
Looks, if any coins in the given money ids to the given type.
If yes, it returns the currency type of the coins.
public string PresentTypes(string type, mixed money)
Returns an array of all currency types, that are in money and
ids to the given type.
public string SingularCoin(string type, mixed money)
returns the currency type, if type means a single coin in money,
otherwise 0.
Now the MONEY_LIB. You can use it either by calling it via
call_other() or inheriting it.
public string *SetValuta(string *str)
sets the valid coin types for trading.
public string *QueryValuta()
returns the valid coin types. When no coin types are set, it returns the
standard coin types for the current uid (either the QueryStandard()
or QueryCoinTypes(uid) of the MONEY_DEMON).
public string *AddValuta(string type)
adds a coin type to the valid coin types.
public varargs int AdjustMoney(object who, mixed amount, string type)
adds the specified money to the money who is carrying.
A money object is cloned, if who wasn't carrying any money.
amount is either an integer (then type has to be a currency type)
or it is a money mapping or a money array.
It returns nonzero, if it was successfully.
public object QueryMoneyObject(object who)
returns either 0 or the money object who is carrying.
public mixed QueryMoney(object who)
returns the money mapping of the money who is carrying.
public varargs int SetMoney(object who, mixed arg, string *types)
Sets the money of who to either the value of arg, build from
coins out of types, or, if arg is a money array or a money mapping,
it sets the money to arg.
public varags int QuerySomeonesValue(object who, string *types)
returns the value of the money who is carrying. If types are
specified, only the matching coins are evaluated.
It returns nonzero for success.
public int PayMoney(object who, mixed money)
pays the given money from the money of who. Returns either
1 if it was successfully or 0, if not.
public varargs PayValue(object who, int value, string *types)
pays the given value from the money of who. If types are
given, only coins of the given types were taken, otherwise
the standard types.
Returns nonzero if successful.
public varargs mixed PayValue2(object who, int value, string *types)
This function is rather more sophisticated than the last one.
It does almost the same than the other one, but there are
different return types for the different cases. The error codes
are defined in <money.h>
MONEY_NEGATIVE is returned, if value is negative.
MONEY_NO_MONEY is returned, if who has no money.
MONEY_NOT_ENOUGH is returned, if who's money has less value than
the given one.
MONEY_CANT_PAY is returned, if who's money has less money of the
specified types, than the given value.
MONEY_WRONG_RESULT should never happen. It is returned if the
result of the paying can't be interpreted.
If the paying was successful, an array of two strings is returned.
The first one describes the money given away by the player,
the second one the change. The strings can be 0, if there is no
money given away or no change came back.
So you can create a message like "You paid " + result[0] +
(result[1]?" and got " + result[1] + " back":"") + "."
public varargs string PayValueString(object who, int value,
string *type, string extramsg,
int width)
This function shall help to deal better with PayValue2(). So it does
some of the interpretations of the result of PayValue2(). It returns
either a string describing the paying to the player ("You paid...")
or 0, if the paying couldn't happen. In this case it sets up a call
to notify_fail() accordingly to the occured error.
The first three arguments are the same to PayValue2(). Additionally
you can give a string containing a message, what the player is paying
for. The last argument gives the width in characters, the text
finally should have. PayValueString() does the formatting itself.
If no width is given, 79 is assumed.
mapping CreateMoneyFromValue(int value, string *types)
Creates a money mapping worth value, consisting of types.
In fact it is a call to MONEY_DEMON->CreateMoney()
mapping CreateMoneyFromString(string str)
Tries to interprete str as a string describing money.
Returns the according money mapping, if successfull, 0 otherwise.
SEE ALSO
money_concepts(C), money-howto(C)