All types within the registered assembly are enumerated and any that derive from
All types within the registered assembly are enumerated and any that derive from
Users can build custom functions used in formulas by sub-classing the
Formulas are entered into the calculation network by first compiling the formula string using the Compile method on the UltraCalcFormula class, then passing the UltraCalcFormula instance to the AddFormula method.
References to formulas that are deleted are recalculated.
This method performs a partial recalculation cycle, yielding after the given number of ticks has expired. This method should be repeately called until it returns false denoting all dirty formulas have been recalculated.
This method recalculates all dirty formulas before returning.
Use the function factory to access detailed information about each function available to formulas compiled against this instance of the calc engine.
The base reference of a formula is sometimes referred to as the Left-Hand-Side (LHS)of an expression. It represents the location within the grid, or other object, whose value is being computed by the given formula. References within the formula expression my be fully qualified or relative to the formula's base reference. For example, if we want to calculate a "[Total]" column in a grid we might have a formula such as "[Units] * [Price]". Each cells within the "Total" column would be computed multiplying the "Units" cell and "Price" cell for row in the band.
Compiling a formula converts the in-fix expression string into an intemediate post-fix form optimized for evaluation.
Compiling a formula converts the in-fix expression string into an intemediate post-fix form optimized for evaluation. If the formula compliation fails, the Error property contains the reason and location of the error. Once formulas are compiled, they may be entered into the calculation network for a given UltraCalcManager instance by calling the UlraCalcEngine.AddFormula method.
The base reference of a formula is sometimes referred to as the Left-Hand-Side (LHS)of an expression. It represents the location within the grid, or other object, whose value is being computed by the given formula. References within the formula expression my be fully qualified or relative to the formula's base reference. For example, if we want to calculate a "[Total]" column in a grid we might have a formula such as "[Units] * [Price]". Each cells within the "Total" column would be computed multiplying the "Units" cell and "Price" cell for row in the band.
Compiling a formula converts the in-fix expression string into an intemediate post-fix form optimized for evaluation.
This property is used by the FunctionBuilder at design-time to provide a link to a help topic describing the function.
The default implementation returns an empty string. In this case, the Designer will not show the Help link."
This property is used by the FunctionBuilder at design-time to provide a link to a help topic describing the function.
The default implementation returns the Func_CategoryURL_Template resource string. The first substitution string argument '{0}' will be replaced by the Func_FUNCTIONNAME_CategoryURL resource. The second substitution string is the Function Name."
AVERAGE(value1, value2, ...)
Value1, value2, ... are one or more numeric values or references to numeric values. An average (arithmetic mean) is calculated by taking the sum of all values, and dividing by the number of values.
Each value is equally weighted. To obtain a weighted average, you can multiply each value by a weight in the expression.
AVERAGE( [Value1]*[Weight1], [Value2]*[Weight2], [Value3]*[Weight3])
SUM(value1,value2,...)
Value1, value2, ... are references for which you want to find the total value. Text representations of numbers and literal numeric constants that you specify in the list of arguments will be included in the sum. If value is a column or vector reference then the sum will be taken of all cells or values contained by the reference. Any error values in the argument list, or text that is not convertible to a numeric value, will produce an error.
CONCATENATE(text1, text2, ..., textN)
Text1, text2, ..., textN are multiple text values that you want to concatenate into one text string. These text values may be text strings, numbers (which will be converted into text), or a single value reference (such as a cell reference) containing such a value.
This function provides for elementary text processing in UltraCalc, such as when building message text or appending some connective text or punctuation to the results of evaluating other text-bearing expressions.
IF( boolean_test, result_if_true, [result_if_false])
Boolean_test is a value (or an UltraCalc expression) which the IF function evaluates to produce a boolean value of either TRUE or FALSE. The outcome of this test determines which result will be returned by the function.
Result_if_true is a value (or the outcome of another UltraCalc expression) that will be returned only when boolean_test has evaluated to the boolean value, TRUE.
Result_if_false is a value (or the outcome of another UltraCalc expression) that will be returned only when boolean_test has evaluated to the boolean value, FALSE.
The IF function allows you to write an UltraCalc expression that branches to one expression (when the boolean_test is TRUE) or another (when the boolean_test is FALSE) based on an arbitrary condition you have specified.
The result_if_false is not specified and boolean_test is FALSE, the IF function will return FALSE.
If boolean_test's evaluation produces an error value then neither Result_if_true nor Result_if_false will be evaluated. Instead, the IF function returns the error value from its evaluation of boolean_test.
ABS( value)
A number's absolute value is it's value without any sign. It represents the magnitude of a value while ignoring it's direction (positive or negative) on a number line or vector.
MOD(numerator, denominator)
Numerator is the number being divided by denominator. When denominator can only be taken from numerator a certain whole number of types (the quotient), any leftover is the remainder.
Denominator is the number dividing the numerator. Any remainder will have the sign of the denominator. This number cannot be zero, otherwise the MOD() function returns a #DIV/0 error.
If you want to perform integer division on these two numbers
then use the
QUOTIENT(numerator, denominator)
Numerator is a numeric value that will be divided by the denominator. It is sometimes called the dividend.
Denominator is the numeric value that divides the numerator. It is sometimes called the divisor. It cannot be zero or a #DIV/0 error value will be returned.
When either the numerator or the denominator is not a number, the QUOTIENT() function returns an error value (#VALUE!).
If you need the remainder from an integer division,
use the
PRODUCT( value1, value2, ..., valueN)
Value1 is the first number (the multiplicand) in a series of numbers that you want to multiply.
Value2 is the second number (the first multiplier) in a series of numbers that you want to multiply.
ValueN is the last number (the last multiplier) in a series of numbers that you want to multiply.
This function offers a convenience when you need to multiply many numbers or expressions at one time.
POWER(value, exponent)
Value is a numeric value or reference to a numeric value which you want to raise to a power.
Exponent is a real number power to which value is to be raised. Imaginary exponents are not supported.
Common applications of the POWER() function occur when you need to multiply a number against itself multiple times. For example, it is common in many computer applications to create bit mask values by raising the value 2 to integer exponents, which produce a sequence such as (1, 2, 4, 8, 16, 32, 64, 128, ...)
The POWER() function additionally supports fractional exponents, and can be used to emulate other functions such as the quad root (raising to an exponent of 0.25, which is 1/4) or the inverse square (raising to an exponent of -2.0).
INT(value)
Value is a real numeric value that you want to
convert into a whole number. INT() is a more specialized version
of the
TRUNC(value, number_of_digits)
Value is a numeric value or reference to a numeric value that you want to truncate.
Number_of_digits specifies the precision at which truncation should occur. By default, truncation occurs zero places right of the decimal point which will produce an integer.
Truncation always discards the fractional value, causing the
Value to move closer to zero (whether it was positive or negative
before the truncation). It differs from the
COUNT(Value1, Value2, ..., ValueN)
Value1, value2, ... valueN can be references to different data structures, such as columns. Each numeric or date/time value is counted. Empty, error, boolean or text values that are not convertible into numeric values are not counted.
When a reference is a range reference, only those numeric and date/time values within the range will be counted.
TRUE() will always evaluate to the boolean value of TRUE. It takes no arguments.
FALSE() will always evaluate to the boolean value of FALSE. It takes no arguments.
NOT(boolean1)
Boolean1 is any boolean (TRUE or FALSE) value, or conditional statement (made up of any UltraCalc expression which itself evaluates to a boolean TRUE or FALSE value) to be inverted.
If boolean1 was TRUE, then the Logical-NOT would return FALSE. If boolean1 was FALSE, then the Logical-NOT would return TRUE.
If Boolean1 is an UltraCalc expression that evaluates to an error value, then the result of a Logical-NOT operation is undefined because an error value is neither TRUE nor FALSE.
AND(boolean1, boolean2, ...)
Boolean1, boolean2, ... are a list of boolean (TRUE or FALSE) values or conditional statements (any UltraCalc expression which itself evaluates to a boolean TRUE or FALSE value) to be evaluated for the constraint that all arguments should be TRUE (or conversely, that at least one argument should be FALSE.)
All arguments are tested (i.e., the logical-AND function does not use "short-circuit" evaluation, in which the function can stop executing as soon as the first argument having the boolean value, FALSE, has been processed.)
This function stops evaluating immediately when any argument results in an error value. An error value is neither TRUE nor FALSE, therefore the return value of the logical-AND function is undefined.
OR(boolean1, boolean2, ...)
Boolean1, boolean2, ... are a list of boolean (TRUE or FALSE) values or conditional statements (any UltraCalc expression which itself evaluates to a boolean TRUE or FALSE value) to be evaluated for the constraint that at least one argument should be TRUE (or conversely, that all arguments should be FALSE.)
All arguments are tested (i.e., the logical-OR function does not use "short-circuit" evaluation, in which the function can stop executing as soon as the first argument having the boolean value, TRUE, has been processed.)
This function stops evaluating immediately when any argument results in an error value. An error value is neither TRUE nor FALSE, therefore the return value of the logical-OR function is undefined.
MIN(Value1, value2, ..., valueN)
Value1, value2, ... valueN are any number of numeric values or references to numeric values from which you want the minimum value found. Arguments may be numbers, boolean values, text values convertible into numbers, or empty. Error values and text values that are not convertible into numbers will produce an error.
The minimum value for a series of numbers can be it's largest magnitude
negative number because larger magnitude negative numbers are less than smaller magnitude
negative numbers. For example, given the expression MIN( -1500, -50, 5, 150), the return value
is -1500 and not 5. To determine the numeric value with the smallest magnitude you would
use the
MIN( ABS(-1500), ABS(-50), ABS(5), ABS(150))
When the argument list is empty, MIN() returns zero.
MAX(Value1, value2, ..., valueN)
Value1, value2, ... valueN are any number of numeric values or references to numeric values from which you want the maximum value found. Arguments may be numbers, boolean values, text values convertible into numbers, or empty. Error values and text values that are not convertible into numbers will produce an error.
When the argument list is empty, MAX() returns zero.
EXP(exponent)
Exponent is the power to which the base, e, is raised. This gives the function it's characteristic "exponential" growth.
Euler's Number, e, is the value 2.718281828459..., and is also the base of the natural logarithm. You can represent the constant e within your UltraCalc formula by specifying EXP(1). The exponential function (and natural logarithm) have many applications in mathematics, engineering, and for modeling behavioral and statistical distributions commonly observed in nature and the social sciences.
ROUND(value, number_of_digits)
Value is a numeric value or reference to a numeric value that you want to round up or down.
Number_of_digits specifies the precision at which rounding should occur. This will be the place value which UltraCalc examines to round up or down. By default, rounding occurs zero places right of the decimal point produces an integer.
PI()
The mathematical constant pi represents the relationship between a circle's diameter and it's circumference. It is also the constant relating the square of a circle's radius with the surface area of the circle. It has a great many applications in mathematics, geometry, the sciences, and engineering.
The constant pi is a non-terminating decimal number, although UltraCalc approximates it to 15 significant digits of precision (3.14159265358979).
A common use of the PI function in UltraCalc is to convert a measurement in radians which is the form in which trigonometric functions take their arguments, and the more conventional degrees of arc. This conversion can be accomplished by multiplying the radian measurement by PI()/180. The following table describes some benchmarks for comparison between radians and degrees.
| Radians | Degrees | Turns of a wheel (common example) |
|---|---|---|
| 0 | 0 | no turns |
| PI/4 | 45 | one-eighth turn |
| PI/2 | 90 | one-quarter turn |
| PI | 180 | one-half turn |
| 2x PI | 360 | one complete turn |
| 3x PI | 540 | one and one-half turn |
SQRT(value)
Value is the numeric value or reference to a numeric value which you are calculating the square root of. Only real roots are supported, therefore if value is negative (which would produce an imaginary root) the SQRT() function will return an error value (#NUM!).
The square root is the number whose product, when the number is multiplied against itself (squared), is value. Note that it is possible to multiply two negative square roots to produce the same positive value. By convention, the SQRT() function only returns the positive root.
COS(value)
Value is the angle measured in radians for which you want to take the cosine. If your argument must be in degrees, multiply it by PI()/180 to convert it into radians.
The cosine is an sinusoidal function with a period of 2*PI()
radians. It's value is always between 1 and -1. It behaves like the sine function,
The cosine function value derives from the geometric ratio between the length of the adjacent (non-hypotenuse) leg to the hypotenuse of a right triangle, when the hypotenuse has a length of one. It is continuous because at intervals of PI() radians the length of the adjacent leg and the hypotenuse are equal.
Another way of looking at this function is to imagine the hypotenuse is the radius, r, of a unit circle centered on a Cartesian plane with x- and y- axes. At any point on the edge of the unit circle, the hypotenuse makes an angle, theta, with the x-axis. The cosine function value of the angle theta is the distance from the center of the circle to the point in the direction of the x-axis. Applied in this fashion, the COS() function can be used to convert between Cartesian and Polar coordinate systems.
Both interpretations are equivalent because if you drop a line from a point on the unit circle that intersects the x-axis at a right angle you form a right triangle.
These trigonometric concepts appear frequently in many engineering, architectural and scientific applications.
ACOS(value)
Value is the real number result of the cosine function taken of an angle you want to find. The legal values of the cosine function are from -1 to 1. An inverse cosine by default will return the normal angle from 0 up to PI. This is because there are several angles which may have an identical value of their cosine. For example, the angles -PI/2, PI/2, 3PI/2, etc., all have a cosine of zero. You can find alternate angles by adding (or subtracting) any multiple of PI radians to the normal angle returned by the inverse cosine function.
You can convert the result of the inverse cosine function from radians into degrees by multiplying it by 180/PI().
ACOSH(value)
Value is the hyperbolic cosine of some angle (measured in radians) that you want
to find. As you might expect, the values of the hyperbolic cosine function (see the
SIN(value)
Value is the angle measured in radians for which you want to take the cosine. If your argument must be in degrees, multiply it by PI()/180 to convert it into radians.
The sine is an sinusoidal function with a period of 2*PI() radians. It's value is always between 1 and -1.
The sine function value derives from the geometric ratio between the length of a right triangle's hypotenuse and the length of the opposite leg, when the hypotenuse has a length of one. It is a continuous function because at intervals of PI() radians the length of the opposite leg and the hypotenuse are equal.
Another way of looking at this function is to imagine the hypotenuse is the radius, r, of a unit circle centered on a Cartesian plane with x- and y- axes. At any point on the edge of the unit circle, the hypotenuse makes an angle, theta, with the x-axis. The sine function value of the angle theta is the distance from the center of the circle to the point in the direction of the y-axis. Applied in this fashion, the SIN() function can be used to convert between Cartesian and Polar coordinate systems.
Both interpretations are equivalent because if you drop a line from a point on the unit circle that intersects the y-axis at a right angle you form a right triangle.
These trigonometric concepts appear frequently in many engineering, architectural and scientific applications.
SINH(value)
Value is an angle measured in radians for which you want to calculate the hyperbolic sine. If your angle is measured in degrees, multiply it by PI()/180 to convert into radians.
Many applications in mathematics and physics, for example determining the gravitational potential of a cylinder, make use of the hyperbolic sine function's characteristics.
ASIN(value)
Value is the sine value of the angle you want. Legal sine values are confined to real numbers from -1 to 1, inclusive.
The angle returned will be between -PI()/2 and PI()/2 radians. To convert this angle into degrees, multiply by PI()/180.
TAN(value)
Value is the angle measured in radians for which you want to take the tangent. If your argument must be in degrees, multiply it by PI()/180 to convert it into radians.
The tangent can have a value from -INF to +INF, however it is undefined at intervals of every PI()/2 radians +/- PI() radians.
The tangent function value derives from a well-known geometric ratio between the length of the opposite and the adjacent (non-hypotenuse) leg of a right triangle. All 3 angles inside of any triangle must add up to exactly PI() radians, and in a right triangle the angle opposite the hypotenuse must be PI()/2 radians. Given these facts, it is not possible for either of the other two angles within the triangle to reach PI()/2 radians themselves. If you choose an angle (other than the triangle's right angle) which approaches PI()/2 radians then the remaining angle must approach 0 radians. The tangent function value tells you in these circumstances how the leg of the right triangle opposite your angle approaches infinite length. These calculations have important applications in architecture and engineering.
TANH(value)
Value is an angle measured in radians for which you want to calculate the hyperbolic tangent. If your angle is measured in degrees, multiply it by PI()/180 to convert into radians. The hyperbolic tangent has a range from -1 to 1.
ATAN(value)
Value is a number containing a tangent function value that you want to retrieve the angle of. This function returns an angle of between PI()/2 and -PI()/2. Although the tangent function is undefined for values of PI()/2 and -PI()/2, the return value of this function is rounded to these values if Value is +INF or -INF, respectively.
This function is sometimes referred to as the inverse tangent function or the arctangent.
The angle returned is the principal value, as there exist an uncountable number of alternative angles satisfying the requirement of having Value as their tangent function value, at regular intervals of +/- PI() to either side of this principal value.
If you require a result in degrees, multiply the arctangent by 180/PI().
ATAN2(x_ordinate, y_abscissa)
X_ordinate is a number representing the distance along the x-axis of a Cartesian point. It may also be thought of as the adjacent leg of a right triangle, where the right angle is made by dropping a perpendicular line from (x_ordinate, y_abscissa) to the point (x_ordinate, 0) on the x-axis.
Y_abscissa is a number representing the distance along the y-axis of a Cartesian point. It may also be thought of as the opposite leg of the right triangle constructed above.
This variation on the arctangent (or inverse tangent function) calculates for you the angle, theta, made with the x-axis when you extend a line segment from the origin at (0, 0) to your specified coordinates at (x_ordinate, y_abscissa). This line segment can also be seen to be the hypotenuse of a right triangle, or the radius of the circle on which the point, (x_ordinate, y_abscissa), sits on the edge. This function is another way of looking at the trigonometric tangent function value that is useful in many UltraCalc applications because it affords you a more convenient parameterization for some tasks, such as converting from Cartesian to Polar coordinate systems.
The return value of this function is within the range of PI()/2 and -PI()/2 measured in radians. If you need to convert this value into degrees then multiply the result by 180/PI().
FLOOR(value)
Value is a real numeric value to be rounded down
to the next lesser whole number (also called an integer). FLOOR()
behaves differently from the
CEILING(number)
Number is the numeric value you want to round.RAND()
The RAND() function will generate another pseudorandom number each time it is evaluated. It returns a fractional number on a unit basis, therefore you can use RAND() to produce numbers between 0 and C by multiplying the RAND() result by C. It follows that to produce a pseudorandom number between A and B you could translate the result by A like this:
RAND() * ( [B] - [A] ) + [A]
The number generation of the RAND() function derives from the system clock, and therefore may not be entirely random. It should not be used for applications requiring cryptographically-strong randomness or uniform probability distributions.
LN(value)
Value is a real number to calculate the natural logarithm of. Value must be positive as the logarithm is undefined for negative values.
A natural logarithm is a special case of a logarithm
having the base of Euler's Number, e (2.71828...). It is the inverse
of the
Logarithms have many applications in mathematics, life and social sciences.
LOG10(value)
Value is a real number to calculate the decimal logarithm of. Value must be positive as the logarithm is undefined for negative values.
To specify your own base for a logarithm use the
LOG(value, [base])
Value is a real number that you want to calculate the logarithm to base for. This number must be positive, as the logarithm is undefined for negative numbers.
Base is the base of the logarithm, which defaults to 10.
To calculate the natural logarithm (a logarithm to the base
of Euler's Number, e) it is usually more convenient to call the
NPV(discountRate, value1, value2, ..., valueN)
DiscountRate is the investment's expected rate of return over the life of the investment, expressed as a percentage growth (or decline) per payment period. In some applications this may be the fixed interest rate. This numeric value is used to discount cash flows paid into or received from the investment.
Value1, value2, ... valueN are any number of numeric values representing cash inflows (as positive numbers) or cash outflows (as negative numbers). These cash flows must occur at a fixed period (the same period at which the discountRate is expressed), although some cash flows may be zero. The order of the sequence is important, as value1 is assumed to occur (N-1) periods before valueN and will have been able to accrue that much more interest at the assumed discountRate.
By convention, the NPV() assumes cash flows occur at the end of each period. Consequently,
the NPV() represents the present value as of the date one period's length before the first cash flow,
value1, has been made. If you require flexibility in when cash flows occur (the beginning or
end of each period), consider using the
Only numeric values or text values convertible to numeric values may be passed to this function. If a column or range reference is passed as a value argument, only numeric values or text values convertible to numeric values are used.
FV(interestRate, nPeriod, payment, presentValue, paymentDue)
InterestRate is the assumed interest rate per period. The future value calculation assumes no change in the interest rate over the course of the investment. If you anticipate interest rate fluctuations, you should calculate the future value incrementally over shorter periods in which the interest rate is held constant. In some calculations, the interestRate may be synonymous with an investments' expected growth or rate of return per period.
NPeriod is the total number of payment periods in an annuity. Each payment is assumed to be of the same amount, and occur at regular fixed time intervals. A payment earlier in the annuity will be invested for a longer period of time and therefore would accrue more interest than a payment made later in the annuity.
Payment is a fixed amount invested in the annuity at each period. Use a negative number to represent an outflow of cash paid out, and a positive number to represent an inflow of cash received. Calculating a future value requires either a non-zero series of payments or a presentValue.
PresentValue is the value of the investment at the beginning of the annuity. It represents the discounted value of a series of future payments, which over time could be worth a greater amount because they have accrued interest. If the annuity has no present value, then you must specify a non-zero payment amount.
PaymentDue is a numeric value of either 1 or 0, and indicates whether payments are invested in the annuity at the beginning of each period (1) or at the end of each period (0).
The interestRate and nPeriod arguments determine the frequency of payments. If interestRate is given as an annual rate, and nPeriod is 1 then payments are once per year. On the other hand, if nPeriod had been 4 then payments would occur quarterly. Please ensure you use consistent time values when specifying these arguments.
PV(interestRate, nPeriods, amount, futureValue, paymentDue)
InterestRate is the per-period rate of interest used to discount the future payments. For positive interest rates, the value of future payments diminishes (discounts) to what they are worth now. It is assumed you can reinvest the present value at interestRate to receive futureValue after nPeriods.
NPeriods are the total number of payment periods over the course of the annuity. If your retirement plan annuitizes in 35-years, and you make a fixed quarterly contribution into it, then you would use 35x4 or 140 as your total number of payment periods.
Amount is how much is paid (or received) each period. This amount must be constant
over the course of the investment. If you need to calculate the Net Present Value of a series of variable
payment amounts, then you should consider using the
FutureValue is the expected cash balance of the investment at culmination. If this argument is omitted, it will be assumed to be zero. In the common usage scenario of calculating loan repayments, a future value of zero represents having a zero liability when the loan is fully repaid. When specifying a zero future value, ensure that amount is non-zero (otherwise the loan could never be repaid). In retirement planning, you would normally estimate the future value you would like to have when you retire.
PaymentDue is a numeric value of either 1 or 0, and indicates whether payments are invested in the annuity at the beginning of each period (1) or at the end of each period (0).
PMT(interestRate, nPeriods, presentValue, futureValue, paymentDue)
InterestRate is the interest rate for the loan.
NPeriods is the number of payments required to pay back the loan.
PresentValue is the current value of the loan (also called the principal), which is a lump sum that the future series of nPeriods payments (which accumulate interest at interestRate) is worth today.
FutureValue is the cash balance in the future (for a loan, this will typically be a loan liability balance of zero) following this series of fixed payments, accruing a fixed interestRate. If omitted, a default future value of 0 is used.
PaymentDue is a numeric value of either 1 or 0, and indicates whether payments are invested in the annuity at the beginning of each period (1) or at the end of each period (0).
NPER(interestRate, amount, presentValue, futureValue, paymentDue)
InterestRate is the rate of interest per payment period. This numeric value must be held fixed for the duration of the investment. If you must calculate financing based on changes in interest rate then you will need to break up the calculation into several stages over which the interest rate is held constant.
Amount is the payment amount due each period. This numeric value must be constant over the duration of the investment.
PresentValue is a discounted value or lump sum payment that if taken today and invested at the interestRate would be worth the same as this series of fixed payments in the future.
FutureValue is the value after the last payment has been made. If this numeric value is omitted it is assumed to be zero (since this function is normally used in calculating loan repayment you will reach zero liability when the loan is finally paid off.)
PaymentDue indicates whether payments come due at the beginning of each payment period (1) or at the end of each payment period (0). If left unspecified, the default is to assume paymentDue occurs at the end of each payment period.
EVEN(Number)
Number is the value to round.ODD(Number)
Number is the value to round.PPMT(interestRate, periodNumber, nPeriods, presentValue, futureValue, paymentDue)
InterestRate is a fixed rate of interest per period. This function assumes there is one payment made on each period, therefore in cases where you want to calculate quarterly or monthly payments you should adjust an annual interestRate accordingly by dividing it by the number of payments per year.
PeriodNumber identifies the period of the current payment, where the first payment has the number 1. The periodNumber must not exceed the total number of periods (nPeriods).
NPeriods is the total number of payments over the course of this investment or loan.
PresentValue is the discounted value of this series of future payments, if you could take a lump sum payment today and invest it at the fixed interestRate until the future date when this investment or loan had been repaid.
FutureValue is the expected value of this series of payments after the last payment has been made, where all previous payments have been accumulating interest at the fixed interestRate. When omitted, such as when this function is used for calculating loan payments that reduce an outstanding liability, the future value is assumed to be zero.
PaymentDue is a numeric value indicating that payments are due at the beginning of each period (1) or at the end of each period (0).
The PPMT() function calculates the portion of a fixed payment attributed to principal. If you
need to calculate the portion of a fixed payment repaying interest then use the
IPMT(interestRate, periodNumber, nPeriods, presentValue, futureValue, paymentDue)
InterestRate is a fixed rate of interest per period. This function assumes there is one payment made on each period, therefore in cases where you want to calculate quarterly or monthly payments you should adjust an annual interestRate accordingly by dividing it by the number of payments per year.
PeriodNumber identifies the period of the current payment, where the first payment has the number 1. The periodNumber must not exceed the total number of periods (nPeriods).
NPeriods is the total number of payments over the course of this investment or loan.
PresentValue is the discounted value of this series of future payments, if you could take a lump sum payment today and invest it at the fixed interestRate until the future date when this investment or loan had been repaid.
FutureValue is the expected value of this series of payments after the last payment has been made, where all previous payments have been accumulating interest at the fixed interestRate. When omitted, such as when this function is used for calculating loan payments that reduce an outstanding liability, the future value is assumed to be zero.
PaymentDue is a numeric value indicating that payments are due at the beginning of each period (1) or at the end of each period (0).
The IPMT() function calculates the portion of a fixed payment attributed to interest. If you
need to calculate the portion of a fixed payment repaying loan principal then use the
LOWER(text_value)
Text_value is a piece of text you want converted into lowercase. The invariant culture is used to translate characters, therefore this function may not be suitable for use with localizable text values.
UPPER(text_value)
Text_value is the text you want to convert to uppercase. UPPER does not change characters in text that are not letters.
LEFT(text_value, num_chars)
Text_value is a piece of text or reference to some text starting with a substring you want to retrieve.
Num_chars indicate the number of characters retrieved from the beginning of text_value. An error value is returned if this argument is less than zero. If this argument exceeds the length of text_value, then all of text_value is retrieved. If omitted, the first character of text_value is retrieved.
RIGHT(text_value, num_chars)
Text_value is a piece of text or reference to some text ending with a substring you want to retrieve.
Num_chars indicate the number of characters retrieved from the end of text_value. An error value is returned if this argument is less than zero. If this argument exceeds the length of text_value, then all of text_value is retrieved. If omitted, the last character of text_value is retrieved.
MID(text_value, starting_point, character_count)
Text_value is a piece of text containing the substring you want to retrieve, when you know the position and length of your desired substring.
Character_count specifies how long of a substring to retrieve from text_value measured as a number of characters. If the requested length, when added to the specified starting_point, exceeds the length of text_value then the remainder of the string starting at starting_point is returned.
Starting_point is the one-based position within text_value of the first character in the substring you want to retrieve. If this argument exceeds the length of text_value then the function will return an empty string.
If either character_count or starting_point has a negative value, or evaluate to an error value, then the function returns an error value.
TRIM(text_value)
Text_value is a piece of text to trim and normalize the white space of. Trimming removes all leading and trailing white space. Normalization reduces runs of consecutive whitespace appearing within the text_value to single blank spaces.
LEN(text_value)
Text_value is any text string or reference to a text value for which you want a character count. The number of characters, including all whitespace, determines the length of the text string.
Depending on the character encoding used, some whitespace characters such as line-breaks may count as two characters (one character is a carriage return, the other character is a line feed).
An empty text string contains no characters.
VALUE(text_value)
Text_value is any text value or single-value reference to a text string that you want to convert into a number. It may have been formatted with a sign, currency symbol, or thousands separator. These characters will be stripped to yield the numeric value of the text.
If the text_value is an error value or could not be converted into a numeric value then the function returns an error value.
Returns an error if the UltraCalcValue argument at the top of the number stack was an error.
Returns a value conversion into a double-precision numeric type if the incoming text can be interpreted as a numeric value (possibly after filtering off thousands separators, decimal separators, currency symbols, exponents and signs.)
Returns a numeric conversion from another numeric type if the incoming argument was not text (sometimes when the result of such a conversion is poorly defined this may defy an application's expectations, for example, a DATEVALUE may convert into a numeric value of ticks.)
FIND(text_to_find, text_to_search, starting_point)
Text_to_find is the piece of text you want to find. It can be a reference (for example, a NamedReference to a constant text string or a CalcSettings reference to a TextBox on the form). It should be shorter in length than the text_to_search.
Text_to_search is the piece of text you want to search for text_to_find within. It's commonly a reference to a text string that you want to search.
Starting_point is the one-based character position inside of text_to_search at which UltraCalc will begin searching. This argument is optional and if omitted, the search will begin at the first character.
If text_to_find is not found this function returns a Value error, otherwise it returns the starting position of text_to_find within text_to_search.
REPLACE(text_value, starting_point, character_count, new_text_value)
Text_value is the original text within which you want to replace some substring of text, and you already know the starting_point and character_count of that substring.
Starting_point is the one-based position within text_value where the replaced substring begins.
Character_count is the length of the substring being replaced as a count of the characters it contains. If this value when added to starting_point would exceed the length remaining in text_value then the entire remainder of text_value is replaced.
New_text_value is some new text that replaces the text of the specified substring. It is not required to be the same length as the replaced substring.
When starting_point or character_count are error values, or less than zero, an error value is returned. If starting_point exceeds the length of text_value then an error value is returned.
It is possible to use the REPLACE() function with other UltraCalc functions to express the replacement of one substring with another. The following UltraCalc expression replaces the word "Old" with the word "New" in the original text value.
REPLACE("Hello Old World", FIND("Old"), LEN("Old"), "New")
SYD(assetCost, salvageValue, lifespan, periodNumber)
AssetCost is the initial value of the asset when it was purchased new. This numeric value needs to be greater than the salvageValue (otherwise the asset would be appreciating in value).
SalvageValue is the market price you can get for an asset at the end of it's useful life (lifespan periods). In some situations, this may represent the value of the asset's spare parts.
Lifespan is the useful life of the asset being depreciated measured in fixed-length time periods (usually years). The appropriate lifespan to use may vary with the kind of asset being depreciated. As the name of this function suggests, the lifespan when using this depreciation method is normally measured in years (although this does not necessarily have to be the case).
PeriodNumber is the one-based number of the period to calculate the depreciation of the asset for, having a value of between 1 and lifespan. It must be measured in the same units of time as the lifespan.
SLN(assetCost, salvageValue, lifespan)
AssetCost is the initial value of the asset when it was purchased new. This numeric value needs to be greater than the salvageValue (otherwise the asset would be appreciating in value).
SalvageValue is the market price you can get for an asset at the end of it's useful life (lifespan periods). In some situations, this may represent the value of the asset's spare parts.
Lifespan is the useful life of the asset being depreciated measured in fixed-length time periods (usually years). The appropriate lifespan to use may vary with the kind of asset being depreciated.
Straight-line depreciation expresses an asset's depreciation at a constant rate per period. The asset is assumed to lose useful value no faster in the first period depreciation is calculated than in the last period. An accountant can advise you as to which assets the straight-line depreciation calculation method is suitable.
DB(assetCost, salvageValue, lifespan, period, months)
AssetCost is the original cost or purchase price of the asset at the start of the calculation.
SalvageValue is the market value of the asset after it's expected useful life ends, sometimes this will be the value of the asset as spare parts.
Lifespan indicates for how many periods the asset is useful (it's useful life), and must be depreciated. Accounting standards vary on what lifespan is appropriate for different classes of assets, such as durable and non-durable goods.
Period indicates the number of units of time between decremental calculations of the depreciation. If lifespan is measured in years, then the value specified for the period must also be in years.
Months allows you to specify the number of months in the first year, if the depreciation does not begin on the first day of the year. You might specify months based on when the asset was purchased new. If omitted, the calculation defaults to 12 which is equivalent to calculating starting from the first day of the year.
For some assets, alternative calculation methods such as the
DDB(assetCost, salvageValue, lifespan, period, weight)
AssetCost is the original cost or purchase price of the asset at the start of the calculation.
SalvageValue is the market value of the asset after it's expected useful life ends, sometimes this will be the value of the asset as spare parts.
Lifespan indicates for how many periods the asset is useful (it's useful life), and must be depreciated. Accounting standards vary on what lifespan is appropriate for different classes of assets, such as durable and non-durable goods.
Period indicates the number of units of time between decremental calculations of the depreciation. If lifespan is measured in years, then the value specified for the period must also be in years.
Weight allows you to fine tune the calculation method. By default, the double declining balance method uses a factor of 2.
For some assets, alternative calculation methods such as the
INTRATE(settlementDate, maturityDate, amount, redemptionValue, basis)
SettlementDate is the date on which a security purchase is settled with the buyer taking possession of the security. Market conventions for settlement of trades vary by security and exchange. The settlement date may be substantially later than a security's issue date when it is traded on the secondary market.
MaturityDate is the date when the security can be redeemed. It ceases to accrue any further value after this date. The maturity date must be later than the settlementDate or an error value is returned.
Amount is the purchase price of the security. For positive interest, this amount will be smaller than the redemptionValue because it discounts interest that will be accrued over the time period the security is held.
RedemptionValue is the price a security holder may redeem their security for at the maturityDate. In some cases, this may be called the face value of the security.
Basis describes what accounting convention to use when counting days per calendar year, and days on which interest can accrue. If omitted, a basis consistent with United States National Association of Security Dealers (NASD) of 30/360 will be employed.
| Basis | Day counting method |
|---|---|
| 0 | 30/360 (US NASD) |
| 1 | Actual/actual |
| 2 | Actual/360 |
| 3 | Actual/365 |
| 4 | 30/360 (European) |
Date values should be passed to this function using either the
DATEVALUE(date_text)
Date_text is text that represents a date in a .NET DateTime formatDATE(year,month,day)
Year is the number representing the year Month is a number representing the month of the year Day is a number representing the day of the monthDAYS360(start_date,end_date,method)
Start_date and end_date are the two dates between which you want to know the number of days. If start_date occurs after end_date, DAYS360 returns a negative number. Dates should be entered by using the DATE function, or as results of other formulas or functions. For example, use DATE(2008,5,23) for the 23rd day of May, 2008. Problems can occur if dates are entered as text. Method is a logical value that specifies whether to use the U.S. or European method in the calculation:TIMEVALUE(time_text)
Time_text is text that represents a date in the .NET DateTime formatTIME(hour,minute,second)
Hour is a number representing the time's hour Minute is a number representing the time's minute Second is a number representing the time's secondMEDIAN(Value1, value2, ..., valueN)
Value1, value2, ..., valueN are any number of numeric values or references to numeric values for which you want the median value found. If any argument is an error value, or there are no numeric values within the series of arguments, then MEDIAN() will return an error value.
The median is the middle value of the sorted list of numeric values (you do not need to sort Value1, value2, ..., valueN prior to passing them to the MEDIAN() function). When the list contains an odd number of values, the median will be the value at position CEIL(N/2). For example, the median of the 5-value list 0, 20, 30, 50, 80, is the value in the third position: 30. When the list contains an even number of values, the median will be the average of the two values in the middle. For example, the median of the 4-value list 7, 20, 30, 45, is the average of the two middle elements (20 and 30): 25. Note that the value of the MEDIAN() varies most from the arithmetic mean of the sorted list when the distribution of values tends to favor one side or the other of that arithemtic mean. For example, the arithmetic mean of the 5-value list 1, 2, 3, 21, 43 is 14 but it's median value is 3.
VAR(Value1, value2, ..., valueN)
Value1, value2, ..., valueN are any number of numeric values or references to numeric values you provide to specify a sampling of your larger data population. If any argument contains an error value or there arte no numeric values in the sampling, the VAR() function evaluates to the first error value it encounters.
Variance is a measure of statistical variability, and is used in statistical studies based on small samplings from much larger data populations to draw inferences about the variability of those data populations.
STDEV(Value1, value2, ..., valueN)
Value1, value2, ..., valueN are any number of numeric values or references to numeric values that you've given to provide a sample space of your data set. If any value contains an error, then the function evaluates to the first error encountered. An error value is returned if the sample space contains no numeric values.
The standard deviation is used in statistical studies to make inferences about a larger population of data based on sampling only a subset. For well chosen samplings, a small standard deviation indicates most data points tend to cluster within a narrow range of values. A larger standard deviations indicates greater variability in the data points, and that there is a higher likelihood for values to occur farther away and/or more frequently away from the expected norm.
TYPE( value)
Value is an UltraCalcValue object or the result of evaluating an UltraCalc expression.
| UltraCalc data type: | TYPE function returns: |
|---|---|
| Number | 1 |
| Text | 2 |
| Boolean | 4 |
| Error | 16 |
ERRORTYPE(error_value)
Error_value is an UltraCalc error value resulting from the unsuccessful evaluation of an expression.
The ERRORTYPE function returns an error value of #N/A (Not Applicable) if you pass it an UltraCalc value that was not an error value.
| Error_value | ERRORTYPE returns |
|---|---|
| #NULL! | 1 |
| #DIV/0! | 2 |
| #VALUE! | 3 |
| #REF! | 4 |
| #NAME? | 5 |
| #NUM! | 6 |
| #N/A! | 7 |
NA()
The NA function always returns the same constant error value.
You might use this function when you wanted an IF function or other complex UltraCalc expression to return the #N/A! error value.
ISBLANK(value)
Value can be any constant, reference or the result of evaluating an UltraCalc expression.
The definition of what constitutes "blank" is anything that causes the IsNull method of the UltraCalcValue object containing the argument, value, to return TRUE. This may vary for different kinds of UltraCalcValue object.
ISERR(value)
Value is an UltraCalcValue object (perhaps the result of evaluating an UltraCalc expression) thought to be an error value. The ISERR function will return FALSE when value is not an error value, or it is an error but the error value was not applicable.
This is a weaker variation of the more stringent
ISERROR(value)
Value is an UltraCalcValue object (perhaps the result of evaluating an UltraCalc expression) thought to be an error value. The ISERROR function will return FALSE only when value is not an error value.
A more relaxed variation of this function is the
ISLOGICAL(value)
Value is an UltraCalcValue object, or the result of evaluating an UltraCalc expression, which is thought to be a boolean value (TRUE or FALSE.) Boolean values are named in honor of George Boole, whose development of Boolean algebra governs the special characteristics of logical functions upon these two values.
Depending on the kind of value, it may not be convertible into a boolean value and therefore the ISLOGICAL function returns FALSE. The ISLOGICAL function only furnishes information about the compatibility of a value with the boolean-typed values evaluated by UltraCalc.
The ISLOGICAL function does not perform deductive reasoning. A return value of TRUE should not be interpreted as proof any value or UltraCalc expression passed to the ISLOGICAL function represents a logical outcome.
ISNA(value)
Value is an error value thought to be the error value returned when an error has happened, but the error code was not applicable.
ISNONTEXT( value)
Value is an UltraCalcValue object or the result of an UltraCalc expression evaluation that you want to test to determine whether it is a text value (such as a .NET String object) or a non-text value.
ISNUMBER( value)
Value is an UltraCalcValue or the result of evaluating an UltraCalc expression that you want to test to determine whether it is a number or not. A numeric value can be an integer, floating-point or decimal number.
ISREF( reference)
Reference is an UltraCalcValue object that contains a reference to some application-specific control, field, or piece of information. You can think of it as an address which the UltraCalc engine uses to look-up a value in your application when one is needed to evaluate an expression.
The ISREF function returns TRUE when the specified UltraCalcValue is a reference. Since it's value is defined by the contents at another referenced location, it's possible for this UltraCalcValue object to change in value based on changes in your application (outside of the UltraCalc engine.) Proper implementation of the IUltraCalcReference interface and NotifyValueChange methods will ensure the UltraCalc engine is made aware of any changes in a referenced value, and that all references depending on this value are refreshed.
Conversely, the ISREF function will return FALSE should the UltraCalcValue you supply represent a constant value or the temporary result of evaluating an UltraCalc expression (a constant value sitting at the top of the UltraCalc engine's number stack.)
ISTEXT(value)
Value is an UltraCalcValue object or the result of evaluating an UltraCalc expression that you want to test to determine whether it is of a text (e.g., string) value or a non-text value (which could be a numeric, boolean, or error value.)
ISEVEN(value)
Value is a number thought to be even (divisible by the
integer 2.) A value that is not an integer will first be converted to
an integer using the
ISODD(value)
Value is a number thought to be odd (not divisible by
the integer 2.) A value that is not an integer will first be converted
to an integer using the
IRR(value_reference, estimate)
Value_reference must be a column or range reference of numeric values representing cash outflows (payments) as negative numeric values, and cash inflows (income) as positive numeric values. Each cash flow must occur with a regular period. If payments occur at irregular intervals, then you must represent the cash flow periods as taking place on a period common to all cash flows, and at intervals without a cash flow specify a zero value. For example, if you finance the purchase of a television by taking a $300 loan with monthly payments of $110, but your payments do not start for three months, your series of cash flows would be monthly but would show three zero values for the months without payments (+300, 0, 0, 0, -110, -110, -110).
Estimate is an approximation close to what you expect the resulting internal rate of return to be. This function employs an iterative algorithm starting with this estimate and then repeatedly converging on a result that has a diminishing margin of error. If you do not provide an estimate then this function uses 10 percent as it's starting point.
If after twenty iterations the margin of error has not closed to within 1/1000 basis point then a #NUM error value will be returned.
The IRR() function has applications where you may be given a series of cash flows without an interest rate, such as in the retail financing example above, and wish to calculate what it's effective rate of interest would be. The internal rate is based on the period between cash flows, therefore when calculating payments that are not annual, you must annualize the internal rate.
RATE(nPeriods, amount, presentValue, paymentDue, futureValue, estimate)
NPeriods are the total number of cash flows, whether a payment (negative amount) or a receipt (positive amount) occuring periodically with a fixed time period between each cash flow.
Amount is the amount of cash paid (negative) or received (positive). It must be held constant over the course of the annuity.
PresentValue is the value today of the series of future payments. Payments made in the future are discounted by the interest rate being calculated, because it is assumed that at that interest rate a smaller sum could be invested today and would grow to the amount at a future time when that payment became due.
PaymentDue indicates whether cash flows occur at the beginning of each period (1) or at the end of each period (0). If not specified, the payments at the end of each period is assumed.
FutureValue is the accumulated balance attained after nPeriods payments have been made and accrued interest at the calculated rate. If left unspecified, the default future value is assumed to be zero (this represents reaching zero loan liability, when a loan has been fully repaid).
Estimate is an approximation of the interest rate used to start the calculation (which works by iteratively refining the estimate until it converges on the correct value). When no estimate is given a default of 10% is assumed.
CODE(Text)
Text is a text string of at least one character in length. This function returns the numeric code of the first character in Text. These code values correspond to those used by your machine to encode the text characters in a string (e.g., Unicode).
If Text is an empty string of zero length, then this function returns the code zero.
FIXED(value, decimal_places, exclude_thousands_separators)
Value is the numeric value to be rounded and formatted as text.
Decimal_places indicate how many places to the right of the decimal point the value should be rounded. If omitted, rounding occurs to two decimal places.
Exclude_thousands_separators is a boolean value (TRUE or FALSE) indicating whether commas should appear in the formatted text value. By default the formatted text includes commas as thousands separators.
This function may not return text values consistent with your locale's formatting of numbers because it operates using culture invariant settings (these include commas as thousands separators and decimal points) to facilitate unambiguously parsing the text values it formats into numeric values for subsequent calculations. Applications may instead choose to format numeric values after UltraCalc has finished processing them, but before presenting them to their end user.
No arguments are passed to this function.
The date returned for TODAY() is based on the local time of the host running UltraCalc. In some distributed applications, such as those built for the Web, this may be different from today's date at the client.
The date/time value returned is always adjusted to Midnight (00:00).
ASINH(value)
Value is the hyperbolic sine of some angle (measured in radians) that you want
to find. As you might expect, the values of the hyperbolic sine function (see the
TANH(value)
Value is an angle measured in radians for which you want to calculate the hyperbolic tangent. If your angle is measured in degrees, multiply it by PI()/180 to convert into radians. The hyperbolic tangent has a range from -1 to 1.
ACOSH(value)
Value is the hyperbolic cosine of some angle (measured in radians) that you want
to find. As you might expect, the values of the hyperbolic cosine function (see the
DATE(date, numberOfMonths)
Date is the starting date
NumberOfMonths is a number of months to shift the date. A positive number means a date after the startdate. A negative number indicates a date prior to the start date.
EOMONTH(date, numberOfMonths)
Date is the starting date
NumberOfMonths is a number of months to shift the date. A positive number means a date after the startdate. A negative number indicates a date prior to the start date.
WEEKDAY(date, returnType)
Date is a date.
ReturnType determines which numbering scheme is used for the days of the week.
1 (default) = Sunday (1) through Saturday (7)
2 = Monday (1) through Sunday (7)
3 = Monday (0) through Sunday (6)
NETWORKDAYS(startDate, endDate [, holiday1, holiday2, ..., holidayN])
StartDate is the date from which to start.
EndDate is the date at which to end.
Holiday1, holiday2, ..., holidayN is any number of dates or range references containing dates that are to be considered non-working days.
WEEKNUM(date, returnType)
Date is a date.
ReturnType determines which day begins the week.
1 (default) = Sunday is the first day of the week.
2 = Monday is the first day of the week.
WORKDAY(startDate, days [, holiday1, holiday2, ..., holidayN])
StartDate is the date from which to start.
Days is the number of work days to offset from the start date.
Holiday1, holiday2, ..., holidayN is any number of dates or range references containing dates that are to be considered non-working days.
Dec2X(number, places)
Number is the decimal value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
Dec2Bin(number, places)
Number is the decimal value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
Dec2Hex(number, places)
Number is the decimal value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
Dec2Oct(number, places)
Number is the decimal value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
X2Dec(number)
Number is a string represeting a number in a non-decimal number system.
Bin2Dec(number)
Number is a string represeting a binary number.
Hex2Dec(number)
Number is a string represeting a hexadecimal number.
Oct2Dec(number)
Number is a string represeting a octal number.
XBase2XBase(number, places)
Number is the value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
Bin2Oct(number, places)
Number is the value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
Bin2Hex(number, places)
Number is the value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
Oct2Bin(number, places)
Number is the value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
Oct2Hex(number, places)
Number is the value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
Hex2Bin(number, places)
Number is the value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
Hex2Oct(number, places)
Number is the value to be converted.
Places is the number of characters to use in representing the value. If places is not specified, the mimumum number of characters neccessary to represent the value will be used. Places allows you to specify leading zeros.
CONVERT(number, fromUnit, toUnit)
Number is the value to convert.
FromUnit is the unit in which the number is given.
ToUnit is the units to convert to.
Weight and mass units:
"g" = gram
"sg" = slug
"lbm" = pound mass (avoirdupois)
"u" = U (atomic mass unit)
"ozm" = Ounce mass (avoirdupois)
Distance units:
"m" = Meter
"mi" = Statute mile
"Nmi" = Nautical mile
"in" = Inch
"ft" = Foot
"yd" = Yard
"ang" = Angstrom
"Pica" = Pica (1/72 in.)
Time units:
"yr" = Year
"day" = Day
"hr" = Hour
"mn" = Minute
"sec" = Second
Pressure units
"Pa" (or "p") = Pascal
"atm" (or "at") = Atmosphere
"mmHg" = mm of Mercury
Force units
"N" = Newton
"dyn" (or "dy") = Dyne
"lbf" = Pound force
Energy units:
"J" = Joule
"e" = Erg
"c" = Thermodynamic calorie
"cal" = IT calorie
"eV" (or "ev") = Electron volt
"HPh" (or "hh") = Horsepower-hour
"Wh" (or "wh") = Watt-hour
"flb" = Foot-pound
"BTU" (or "btu") = BTU
Power units:
"HP" (or "h") = Horsepower
"W" (or "w") = Watt
Magentism units:
"T" = Tesla
"ga" = Gauss
Temperature units:
"C" (or "cel") = Degree Celsius
"F" (or "fah") = Degree Fahrenheit
"K" (or "kel") = Kelvin
Liquid measure units:
"tsp" = Teaspoon
"tbs" = Tablespoon
"oz" = Fluid ounce
"cup" = Cup
"pt" (or "us_pt") = U.S. pint
"uk_pt" = U.K. pint
"qt" = Quart
"gal" = Gallon
"l" (or "lt") = Liter
Any metric ToUnit or FromUnit may be prefixed with one of the following:
exa ("E") = 1E+18
peta ("P") = 1E+15
tera ("T") = 1E+12
giga ("G") = 1E+09
mega ("M") = 1E+06
kilo ("k") = 1E+03
hecto ("h") = 1E+02
dekao ("e") = 1E+01
deci ("d") = 1E-01
centi ("c") = 1E-02
milli ("m") = 1E-03
micro ("u") = 1E-06
nano ("n") = 1E-09
pico ("p") = 1E-12
femto ("f") = 1E-15
atto ("a") = 1E-18
DELTA(number1, [number2])
Number1 is a number.
Number2 is a number. If Number2 is not specified, Number1 will be compared to 0.
GESTEP(number, [step])
Number is a number.
Step is a number. If step is not specified, Number will be compared to 0.
COMPLEX(realNumber, imaginaryNumber, [suffix])
RealNumber is the real coefficient of the complex number.
ImaginaryNumber is the imaginary coefficient of the number.
Suffix specifies the suffix to use. The acceptable values are "i" or "j". If omitted, "i" is used. Note that the suffix is case-sensitive; upper case "I" and "J" are not allowed and will result in a #VALUE error.
IMABS(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMAGINARY(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMARGUMENT(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMCONJUGATE(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMCOS(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMDIV(dividend, divisor)
Dividend is a complex number in the format: "x + yi" or "x + yj".
Divisor is a complex number in the format: "x + yi" or "x + yj".
IMEXP(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMLN(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMREAL(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMSUB(complexNumber1, complexNumber2)
ComplexNumber1 is a complex number in the format: "x + yi" or "x + yj" from which ComplexNumber2 will be subtracted.
ComplexNumber2 is a complex number in the format: "x + yi" or "x + yj" which will be subtracted from ComplexNumber1.
IMPRODUCT(complexNumber1 [, complexNumber2, complexNumber3, ..., complexNumberN])
ComplexNumber1, ComplexNumber2, ..., ComplexNumberN is any number of complex numbers in the format: "x + yi" or "x + yj" which will be multiplied together.
IMSUM(complexNumber1 [, complexNumber2, complexNumber3, ..., complexNumberN])
ComplexNumber1, ComplexNumber2, ..., ComplexNumberN is any number of complex numbers in the format: "x + yi" or "x + yj" which will be added together.
IMLOG10(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMLOG2(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMSIN(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMSQRT(complexNumber)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
IMPOWER(complexNumber, power)
ComplexNumber is a complex number in the format: "x + yi" or "x + yj".
Power is the power to which ComplexNumber will be raised.
DollarFr(decimalDollarAmount, Fraction)
DecimalDollarAmount is the dollar amount expressed as a decimal.
Fraction is the value used as the denominator of the fraction. If this value is not an integer, it will be truncated.
DollarFr(decimalDollarAmount, Fraction)
DecimalDollarAmount is the dollar amount expressed as a decimal.
Fraction is the value used as the denominator of the fraction. If this value is not an integer, it will be truncated.
INFO(type)
Type is a string indicating the type of information to return.
"directory" = The full path to the current folder.
"osversion" = The currently operating system version as a string.
"system" = The current operating system. This will always return "pcdos" which indicates Microsoft Windows. The corresponding function in Excel can also return "mac" for Macintosh, but since NetAdvantage is only supported in Windows, this function will always return "pcdos".
The following are supported by Microsoft Excel, but have no correlation in UltraCalcManager: "numfile", "origin", "recalc", "release".
The following are supported in older versions of Excel, but not Office2007, and have no correlation in UltraCalcManager: "memavail", "memused", "totmem".
N(value)
Value is the value to be converted to a number. The following are acceptable values:
A number - returns the number.
A date - returns the date.
True - returns 1.
False - returns 0.
An error value - returns the error value.
Any other value - returns 0.
FACT(number)
Number is a positive number for which the factorial will be calculated.
FACTDOUBLE(number)
Number is a positive number for which the double factorial will be calculated.
Combin(number, numberChosen)
Number is the number of items.
NumberChosen is the number of items chosen in each combination.
DEGREES(radians)
Radians is a value in radians which will be converted to degrees.
RADIANS(degrees)
Degrees is a value in degrees which will be converted to radians.
GCD(number1, [number2, number3, ..., numberN])
Number1, Number2, ..., NumberN is any number of integers.
LCM(number1, [number2, number3, ..., numberN])
Number1, Number2, ..., NumberN is any number of integers.
MULTINOMIAL(number1, [number2, number3, ..., numberN])
Number1, Number2, ..., NumberN is any number of numbers.
MRound(number, multiple)
Number is a number to be rounded.
Multiple is a number indicating the multiple to which to round.
RANDBETWEEN(bottom, top)
Bottom is the minumum value that will be returned.
Top is the maximum value that will be returned.
ROMAN(number, form)
Number is the number to convert to roman numerals.
Form is a number or boolean value indicating whether to use classic roman numerals or a more concise version.
0 = (Default) Classic. (499 = "CDXCIX")
1 = More concise. (499 = "LDVLIV")
2 = More concise. (499 = "XDIX")
3 = More concise. (499 = "VDIV")
4 = Simplified. (499 = "ID")
TRUE = Classic.
FALSE = Simplified.
ROUNDDOWN(number, digits)
Number is a number to be rounded down.
Digits indicates the number of decimal places to round to. Positive numbers indicates places after the decimal point, negative numbers indicate places before the decimal point.
ROUNDUP(number, digits)
Number is a number to be rounded up.
Digits indicates the number of decimal places to round to. Positive numbers indicates places after the decimal point, negative numbers indicate places before the decimal point.
SERIESSUM(inputValue, initialPower, step, coefficient1 [, coefficient2, coefficient3, ..., coefficientN])
InputValue is the input value to the power series.
InitialPower is the initial power to which X will be raised.
Step is the step which will be used to increase N for each term in the series.
Coefficient1, Coefficient2, ..., CoefficientN is a set of coefficients by which each successive power of X is multiplied.
SIGN(number)
The number whose sign wil be returned.
SQRTPI(number)
The number which will be multiplied by Pi.
CHOOSE(index_num, value1, [value2, ..., valueN])
REPT(text_value, repeat_count)
Text_value is the text which should be repeated.
Repeat_count is the positive number of times text_value should be repeated.
When repeat_count is negative, and error value is returned. When repeat_count is 0, an empty string is returned. When repeat_count is not an integer, it will be truncated.
If the length of the returned string would be greater than 32,767, an error value is returned.
REPT("-", 10)
Subtotal(function_num, ref1, ref2,...)
Function_num is the type which should be calculated.
| Function_num (includes hidden values) | Function_num (ignores hidden values) | Function |
|---|---|---|
| 1 | 101 | AVERAGE |
| 2 | 102 | COUNT |
| 4 | 104 | MAX |
| 5 | 105 | MIN |
| 6 | 106 | PRODUCT |
| 7 | 107 | STDEV |
| 9 | 109 | SUM |
| 10 | 110 | VAR |
Ref1, ref2, ... are references for which you want to find the subtotal.
Text(value, format_text)
value is the numeric value which should be formatted.
format_text is a the number format with which to format the value.
IFERROR(value, value_if_error)
value is the value to use when it is not an error.
value_if_error is the value to use if the value argument is an error.
COUNTA(Value1, Value2, ..., ValueN)
Value1, value2, ... valueN can be references to different data structures, such as columns. Each non-blank value is counted.
When a reference is a range reference, only the non-blank values within the range will be counted.
SEARCH(search_text, value, [start_index])
search_text is the text to find in value.
value is the text in which to find search_text.
start_index is the 1-based index in which to start the search (if omitted, the start_index is 1).
SEARCHB(search_text, value, [start_index])
search_text is the text to find in value.
value is the text in which to find search_text.
start_index is the 1-based index in which to start the search (if omitted, the start_index is 1).
AVEDEV(number1, number2, ...)
Number1, number2, ... are one or more numeric values or references to numeric values.
Once the assembly is loaded, any type that derives from
Once the assembly is loaded, any type that derives from UltraCalcFunction will be registered with the function factory
The number stack is used for evaluating formulas. When formulas are compiled, the formula tokens are placed in a collection in post-fix, or Reverse Polish Notation (RPN) format. RPN format arranges the formula token list so each sub-expressions's terms are placed before their operator, and sub-expressions are ordered to enforce correct operator precedence. This format allows the formula evaluate method to loop through the formula token collection front to back pushing an operator's terms onto the number stack until an operator is reached. Each time an operator is reached, it's subexpression is computed and resulting value pushed onto the number stack. Once the end of the end of the formula collection is reached, the formulas calculated value is at the top of the number stack.
The CalcSettings object defines properties that determine how the
In order for any control to be used in the Calculation Network, a CalcSettings must be created for that control. This can be done by creating a new CalcSettings and adding it to the network via the
Always be certain to set the
You can create a new CalcSettings object and add it into the calculation network via the
You can create a new CalcSettings object and add it into the calculation network via the
You can create a new CalcSettings object and add it into the calculation network via the
This method will reset all properties of the
Returns a string containing the PropertyName and the Formula of the
The Formula property will be used to calculate a value and that value will be set on a property of the control as indicated by the
It is strongly recommended that any control with a formula be marked ReadOnly. A control that is the target of a formula calculation should not be edited by the user, because any user-edited value will be overwritten by the calculated value. Also, if a control is used as both the target and the source of a formula, then the source value will always use the calculated value and not the value displayed in the control after a user edit.
PropertyName gets/sets the name of the property that is used as either the source or target (or both) of any calculations involving the control. If no PropertyName is set, or if the PropertyName is invalid, then the control will not participate in any calculations and a Reference Error may be generated.
In order for the CalcManager to properly use a control's proeprty as the source value in a calculation the property must follow the same guidelines as a Bindable property. That is, the control must expose the property publicly and also expose a PropertyChanged event. For Example, if The Text property is being used, then the control must also have a TextChanged event. If there is no such event, the calculation will not function correctly. This applies only to source properties. If the control is only being used at the target for the calculated value of a formula, the event is not required.
The Alias is use to identify a control in a formula by something other than it's Name. If no Alias has been set, then the control can be referred to by it's name in any calculation. If an Alias has been set, then the Alias must be used instead.
Returns the name of the control if no
When a Calculation or Reference error occurs during the evaluation of a formula, the UltraCalcManager will display an ErrorProvider Icon adjacent to the target control. ErrorIconAlignment determines the location of the icon. When set to Default, the
When a Calculation or Reference error occurs during the evaluation of a formula, the UltraCalcManager will display an ErrorProvider Icon adjacent to the target control. ErrorIconAlignment determines the location of the icon. The resolve process will look at the
If a Calculation or Reference Error occurs during a calculation, ErrorValue can be used to specify a default value to be used for display or saving. When an error occurs in a calculation, this value will be assigned to the appropriate property of the Context object. For example, in the case of a TextBox's Text property, the property itself will be set to the error value so that it both displays in the TextBox and is saved if the Text property is bound. In the case of an UltraGrid cell, this value will not be displayed, but will be saved to the underlying data source. Objects that do not display or bind, such as a NamedReference, will ignore the ErrorValue.
Value returns the current value that any calculations referencing the control will use. If the control is the target of a formula, then this will be the last calculated value.
Note that the value may be an UltraCalcValueError.
TreatAsType is useful if you are using values in a Calculation that are not neccessarily in the native type for the formula. For example, if a TextBox control's Text property is being used to enter a numeric value, the CalcManager will, by default, convert that contents of the TextBox to a Double using the Invariant Culture. This may not always be the desired effect. Setting TreatAsType to double in this example would convert the Text of the TextBox to a Double using the Current (instead of Invariant) Culture before passing the value on to the CalcManager.
Setting TreatAsType also allows the CalcManager to validate the data and display an error if it cannot be converted to the appropriate type. This means that if TreatAsType has been set and the property value of the control cannot be converted to the proper type, an ErrorIcon will be displayed. Without setting TreatAsType, only controls which are using the control as a source will be able to display an error.
This is used to convert a
It also allows expanding the properties of the object in the PropertyGrid.
This class is a UITypeEditor for the
This class provides a dropdown list of types for the
The Formula property will be used to calculate a value for the cells in this column.
It is strongly recommended that any column with a formula be marked ReadOnly. A column that is the target of a formula calculation should not be edited by the user, because any user-edited value will be overwritten by the calculated value. Also, if a column is used as both the target and the source of a formula, then the source value will always use the calculated value and not the value displayed in the column after a user edit.
If a Calculation or Reference Error occurs during a calculation, ErrorValue can be used to specify a default value to be used for display or saving. When an error occurs in a calculation, this value will be assigned to the appropriate property of the Context object. For example, in the case of a TextBox's Text property, the property itself will be set to the error value so that it both displays in the TextBox and is saved if the Text property is bound. In the case of an UltraGrid cell, this value will not be displayed, but will be saved to the underlying data source. Objects that do not display or bind, such as a NamedReference, will ignore the ErrorValue.
This enumeration is used by the
This enumeration is used by the
When set to Default, an individual CalcSettings will walk up to use the setting of the UltraCalcManager. If the UltraCalcManager is also set to Default, then MiddleRight will be used.
This enumeration lists all of the possible properties of the objects in the UltraWinCalcManager namespace. These are used in the
This enumeration is used to specify an event when calling the
This enumeration is used to specify a group of events when calling the
For internal use only.
Determines if the specified event is currently in progress.
Returns whether a particular event is enabled.
This method can be used to enable or disable the firing of a specific event.
Note that disabling an event does not prevent any internal processing by the component. It merely prevents the event handler from being called.
Returns whether a group of events is enabled.
This method can be used to enable or disable the firing of a group of events.
Note that disabling an event does not prevent any internal processing by the component. It merely prevents the event handler from being called.
The Context indicates the object which was changed. This can be any object that particpates in the calculation network such an UltraGridCell, NamedReference, Control, etc.
The action indicates what type of change occurred. See the
Gets / sets whether to display an error message to the user.
Gets / sets whether to display an error message to the user.
This property indicates the control whose value is being retrieved or set by the CalcManager.
In the case of the ParseValue event, Value will return the value read from the control. Changing the Value in this event will change how the CalcManager interprets the value. For example, in order to use a formatting number like "$5.00", it must be converted into a numeric value like "5.0".
In the case of the FormatValue event, Value will return the value from the Calcmanager that is about to be assigned to a property on the control. Changing the Value in this case will assign the newly changed value to the control instead. So this can be used to change the value, the datatype, or simply to format the value into a more user-friendly display.
Set Handled to True to indicate that a parsing was handled. This means that the TreatAsType property will be ignored for this conversion.
The DesiredType indicates the
The
CalcValue returns the UltraCalcValue being used by the CalcManager. This is provided so that the programmer can detect special situations like the occurance of a CalculationError.
This property returns the
This class is for internal infrastructure only and should not be used.
A NamedReference is a reference in the calculation network with no associated control.
By creating a NamedReference with a
To get the calculated value of a NamedReference, use the
In order for a
In order for a
In order for a
In order for a
The Formula property will be used to calculate a value and that value will be returned by the
Category is used to organize NamedReferences into groups in the Formula designer.
Value returns the current value that any calculations referencing the NamedReference will use. If the NamedReference is the target of a formula, then this will be the last calculated value.
Note that the value may be an UltraCalcValueError.
This is used to convert a
It also allows expanding the properties of the object in the PropertyGrid.
Add
This method creates a new new
This method adds a
This method will insert a
Note that the order of items in the
This method removes the
If the specified
This method removes the specified
If the specified
This method removes the
This method clears the collection, removing all of the items from the collection and from the calculation network.
This method is intended for internal use only. It is used to add an array of
This property returns the
The UltraCalcManager component creates a calculation network which can include controls (via
Each item in the network is called a reference. A reference can be a
This methods clears the
Calling SuspendCalc will temporarily suspend any automatic calculations performed by the
Note that the suspension refers to automatic calculations only. This means that calculations that would normally be performed on a timer when
Note also that each time SuspendCalc is called, a counter is incremented. So the same number of
The ResumCalc method will resume automatic calculations after a preceding call to the
Note also that each time SuspendCalc is called, a counter is incremented. So the same number of
This method is typically used when you are about to perform operations in
UltraWinGrid that will cause a large number of calculation-related notifications to be raised.
Sometimes processing a large number of notifications can take a very long time. This method
can be used to suspend such processing of notifications.
This method will cause the
The ReCalc method forces the synchronous recalculation of all formulas in the calculation network.
When the
When the
When the
Developers can use this method to limit the amount of time in the time slice _CALCMANAGER_ spends performing it's calculations. If all calculations have been completed before this time interval elapses, control returns immediately to the caller. Setting this interval too small can lead to excessive task-switching that would make the calculation complete more slowly than it ordinarily would have completed, therefore developers are advised to allot as much time as the user-responsiveness of the application permits.
All types within the registered assembly are enumerated and any that derive from
Users can build custom functions used in formulas by sub-classing the
This method allows the programmer to manually mark the CalcSettings of a control dirty. This is usually not necessary, depending on the
The Calculate method allows you to calculate a formula once without creating a
This method does not ensure that any dependants of the specified formula are calculated. When using a
This method throws an exception if the formula has a syntax error. Any other kind of error is returned as an instance of
Use this method to get the
In order for any control to be part of the calculation network, the
This method associates a
Use this method to determine if a CalcSettings object has been created and contains data that needs to be serialized.
This method resets the
Use this method to determine if a DataGridViewColumnCalcSettings object has been created and contains data that needs to be serialized.
NamedReferences are useful for creating formulas or constants that are used in other calculations but which will not be displayed to the user.
The CalcFrequency property determines when calculations are performed. They can be performed asynchronously on a timer, synchronously every time a value changes, or manually only when the
By default, calculations are done Asynchronously on a timer. This ensures that the UI thread is not locked up when long or complex calculations are performed. The disadvantage to this mode is that a particular value may not be calculated when it is requested in code. When retrieving a calculated value using Asynchronous mode, you should call the
Synchronous mode will updated all calculations immediately any time a source value of a calculation changes. Unlike Asynchronous mode, values can always be depended upon to be calculated when asked for. The disadvantage of this mode is that long or complex calculations may lock the UI thread until they are complete.
In Manual mode, no calculations are performed by the
The EventManager gives you a high degree of control over how the component invokes event procedures. You can use it to selectively enable and disable event procedures depending on the context of your application. You can also use the event manager to return information about the state of the component's events.
The event manager's methods are used to determine the enabled state of an event (
When a Calculation or Reference error occurs during the evaluation of a formula, The UltraCalcManager will display an ErrorProvider Icon adjacent to the target control. ErrorIconAlignment determines the location of the icon. When set to Default, MiddleRight is used. This setting can be overridden on any individual control by setting the
The display of the icon varies depending on the context. A control on a form will show the icon as part of an ErrorProvider. NamedReferences show no icons. UltraWinGrid will not show the icon.
This property only applies when
AsynchronousCalcDuration determines how much time is used by the CalcManager to perform pending calculations. Each time the interval specified by
To force all calculations to be completed each time the Interval passes, set this property to -1.
This property only applies when
AsynchronousCalcInterval determines how much time elapses between calculations. Each time the Interval passes the CalcManager will perform pending calculations for a period of time specified by
When true, certain calculations will be deffered if they are not visible. This is mainly used for iterated calculations, such as UltraGrid cells. If possible, cells that are in view will be calculated before cells that are out of view.
Note that in some cases, deferring calcalations is not possible. For example, if there is a Summary on a column, then all the values in the column must be calculated before the summary can be calculated.
CalculationsCompleted event is fired when all calculations are completed. In Asynchronous mode, this even will fire only when all calculations have been computed and no references are dirty.
ValueDirtied event is fired any time a value that is being used in a calculation is dirtied (changed). This even can be used in conjunction with a CalcFrequency setting of Manual to determine when to there are dirty calculations to be ReCalced.
This event fires any time the
FormulaCircularityError is fired any time a formula attempts to reference itself either directly or indirectly.
Circular references cannot be resolved by the UltraCalcmanager and so no calculations involving circular references will be performed.
This event fires whenever the
FormulaCalculationError event is fired any time the attempt to calcuate a formula results in an error, whether it be a reference, syntax, or mathematical error..
ParseValue event is fired any time a CalcSettings retrieves a value from a control. The Value can then be modified by before it passed back to the CalcManager for the purposes of formatting, type conversion, etc.
Note that if a control is both the source and target of a formula, the ParseValue event will not fire because the CalcManager does not retrive the value from the control. Instead, the CalcManager uses the calculated result of the formula. This means that a control that is being used as both source and target can safely be Formatted using the
FormatValue event is fired any time a CalcSettings is about to set a value on a control. The Value can then be modified by before it is assigned to the control for the purposes of formatting, type conversion, etc.
This event fires any time the result of a