## Double Functions

The double functions are those functions that:

- take one or more arguments that are double expressions and
- return a double value

Some terms that are used in this document:

- radians
- pi

The set of available double functions is:

- one argument functions:

  Function Name | Description | Notes
  --- | --- | ---
  acsc | inverse cosecant | acsc(value) = asin(1.0 / value)
  acsch | inverse hyperbolic cosecant | acsch(value) = asinh(1.0 / value)
  acos | inverse cosine | result = cos(value), value = acos(result) The cosine accepts an angle measured in radians and returns a value between -1 and 1 so the inverse cosine expects a value between -1 and 1 and returns an angle in radians. 0 <= result <= pi
  acosh | inverse hyperbolic cosine | acosh(value) = log(value + sqrt(value * value - 1.0))
  acot | inverse cotangent | acot(value) = atan(1.0 / value)
  acoth | inverse hyperbolic cotangent | acoth(value) = atanh(1.0 / value)
  asec | inverse secant | asec(value) = acos(1.0 / value)
  asech | inverse hyperbolic cosecant | asech(value) = acosh(1.0 / value)
  asin | inverse sin | result = sin(value), value = asin(result) The sine accepts an angle measured in radians and returns a value between -1 and 1 so the inverse sine expects a value between -1 and 1 and returns an angle in radians. 0 <= result <= pi
  asinh | inverse hyperbolic sine | asinh(value) = log(value + sqrt(value * value + 1.0))
  atan | inverse tangent | result = tan(value), value = atan(result) The tangent accepts an angle measured in radians and returns a real number so the inverse tangent accepts a real number and retuns an angle measured in radians. -pi/2 <= result <= pi/2
  atanh | inverse hyperbolic tangent | atanh(value) = log((value + 1.0) / (value - 1.0)) / 2.0
  bernoulli | bernoulli numbers | bernoulli(n) = the nth bernoulli number (n < 40)
  bit_not | bitwise not | bit_not(value) = value is rounded to an integer and is then returned with each 0 bit turned to a 1 and vice versa. bit_not(12312322) = -12312323.
  ceil | ceiling function | This function rounds its argument upward to the nearest integer. For example: ceil(1.9) == 2.0.
  cos | cosine | The cosine expects arguments passed to it to be numbers measured in radians. The cosine is a cyclical function with a period of 2 * pi, that is - every 2 * pi it repeats itself so: cos(0) == cos(2 * pi) == cos(-2 * pi) == cos(4 * pi) -1 <= cos(value) <= 1
  cosh | hyperbolic cosine | cosh(value) = (exp(value) + exp(-value)) / 2.0
  cot | cotangent | cot(value) = cos(value) / sin(value)
  coth | hyperbolic cotangent | coth(value) = cosh(value) / sinh(value)
  csc | cosecant | csc(value) = 1.0 / sin(value)
  csch | hyperbolic cosecant | csch(value) = 1.0 / sinh(value)
  deg2rad | convert degrees to radians | deg2rad(360) = 2 * pi
  euler | euler numbers | euler(n) = the nth euler number (n < 40)
  exp | exponential | The value of the exponential function is the result of raising euler's number (approximately 2.7182818284590452354) to the power of the argument supplied. exp(value) is: 2.7182818284590452354 ^ (x) Where '^' means "raised to the power of"
  abs | absolute value | The absolute value of a real number x is defined as: abs(x) = x (if x >= 0) example: abs(2) = 2 abs(x) = -x (if x < 0) example: abs(-1) = 1 Note that abs(x) is always positive.
  fabs | absolute value | alternate name for abs
  fact | factorial | fact(value) = value * (value - 1) * (value - 2) * ... * 1
  floor | floor | This function rounds its argument downward to the nearest integer. For example: floor(1.2) == 1.0.
  get_entry_red | access color table rgb values | This function returns the red component for the specified color table entry index. For example:
            colors { define { [255 0 0] } }

            formula {
               println(get_entry_red(0));
               ...
  Will print out '255'
  get_entry_green | access color table rgb values | This function returns the green component for the specified color table entry index.
  get_entry_blue | access color table rgb values | This function returns the blue component for the specified color table entry index.
  log | natural log | The log of x is the power that euler's number (approximately 2.7182818284590452354) must be raised to to equal x. The natural log is the inverse of the exp function, that is: log(exp(x)) == x Note that the natural logarithm function expects its argument to be greater than zero.
  log10 | log base 10 | The value of log10(x) is the power that 10 needs to be raised to to be equal to x. For example: log10(100) == 2 (since 10 * 10 == 100) Like the natural logarithm, log10 expects its argument to be greater than zero.
  rad2deg | convert radians to degrees | rad2deg(2 * pi) = 360
  sec | secant | sec(value) = 1.0 / cos(value)
  sech | hyperbolic secant | sech(value) = 1.0 / cosh(value)
  sin | sine | The sine expects arguments passed to it to be numbers measured in radians. The sine is a cyclical function with a period of 2 * pi, that is - every 2 * pi it repeats itself so: sin(0) == sin(2 * pi) == sin(-2 * pi) == sin(4 * pi) -1 <= sin(value) <= 1
  sinh | hyperbolic sine | sinh(value) = (exp(value) - exp(-value)) / 2.0
  sqrt | square root | The square root of x is the number that when multipled by itself is equal to x. For example: sqrt(4) == 2. The square root expects its argument to be greater than or equal to zero.
  tan | tangent | tan(value) = sin(value) / cos(value)
  tanh | hyperbolic tangent | tanh(value) = sinh(value) / cosh(value)

- two argument functions:

  Function Name | Description | Notes
  --- | --- | ---
  atan2 | the inverse tangent | Similar to atan except that two arguments are used - also, the range of returned values is different. With the exception of the range of return values, the following is true: atan2(y, x) == atan(y / x) -pi <= atan2(y, x) <= pi
  bit_and | bitwise and | The bitwise and of the two supplied arguments (each rounded to integers). bit_and(5, 2) = 0
  bit_or | bitwise or | The bitwise or of the two supplied arguments (each rounded to integers). bit_or(5, 2) = 7
  bit_shl | bitwise left shift | The shift the bits of the first argument left by the number of positions specified by the second argument (both rounded to integers). bit_shl(1, 5) = 32
  bit_shr | bitwise right shift | The shift the bits of the first argument right by the number of positions specified by the second argument (both rounded to integers). bit_shr(64, 3) = 8
  bit_xor | bitwise exclusive or | The bitwise xor of the two supplied arguments (each rounded to integers). bit_xor(5, 3) = 6
  mod | the modulus or remainder function | To compute mod(x, y) calculate the value 'n' by dividing x by y and rounding the result towards zero to an integer. The return value of mod(x, y) then is: x - n * y The mod function expects that its second argument is not zero. Some examples: mod(10, 2) == 0 mod(10.1, 2) == 0.1 mod(10.5, 2) == 0.5 mod(11, 2) == 1.0 mod(11.2, 2) == 0.2 mod(11.5, 2) == 1.5 mod(12, 2) == 0 the returned value is a real number >= 0 and less than the first argument. In the above examples, note that 2 is the second argument to mod and that the result is always less than 2. NOTE: You can also write mod(x, y) as "x % y"
  fmod | the modulus or remainder function | alternate name for 'mod'
  pow | the power function | This function raises the first argument to the power of the second argument Here are some examples pow(2, 3) == 8 (2 * 2 * 2) pow(3, 4) == 91 (3 * 3 * 3 * 3) The pow function can handle any two real values except when the first argument is negative and the second argument is not an integer. NOTE: You can also write pow(x, y) as "x ^ y"
  min | the minimum function | if a <= b then min(a, b) = a if a < b then min(a, b) = b
  max | the maximum function | if a >= b then max(a, b) = a if a < b then max(a, b) = b
  gamma | the gamma function | This function can be used to adjust color values. 0 <= first argument <= 255 0 < second argument gamma(x, y) = 255 * ((x/255) ^ (1 / y)) values of y closer towards zero produce darker colors, values of y farther from zero produce lighter colors

- three argument functions:

  Function Name | Description | Notes
  --- | --- | ---
  get_sin_color | maps value (0 <= value <= 1) to an rgb value (0 <= rgb <= 255) | This function is very useful when doing direct color fractals. Its arguments: first argument (value to be mapped) => 0 <= value <= 1 second argument (start value) => 0 <= value <= 255 third argument (step value) => 0 < value This function produces a smooth color gradient using a sin and cos transformation of the original value (0 <= value <= 1). It returns a value between 0 and 255.
  get_cos_color | like 'get_sin_color', maps value (0 <= value <= 1) to an rgb value (0 <= rgb <= 255) | This function is very useful when doing direct color fractals. Its arguments: first argument (value to be mapped) => 0 <= value <= 1 second argument (start value) => 0 <= value <= 255 third argument (scale value) => 0 < value This function uses the following formula to compute its return value: offset = pi * (offset / 255.0) result = cos(offset + pi + scale * value * 2 * pi) return(127.5 * (1.0 + result)); Again, like 'get_sin_color' it returns a value between 0 and 255.
  get_hsv_red | Given h, s and v - return the red component that results from performing a hsv => rgb conversion
  get_hsv_green | Given h, s and v - return the green component that results from performing a hsv => rgb conversion
  get_hsv_blue | Given h, s and v - return the blue component that results from performing a hsv => rgb conversion

- additional functions

  map_color - can accept a variable number of arguments. It is also useful for making direct color fractals. The general format of map_color is:

  map_color(value : colors : percentages)

  The first argument 'value' will be a number: 0 <= value <= 1

  The 'colors' argument will be a comma separated list of values between 0 and 255.

  The 'percentages' argument will be a comma saparated list of values between 0 and 100 (0% and 100%).

  Here's an example of how map color might be used:

  $value = .5;
  $result = map_color($value : 0, 255 : 100);

  In this example, a $value of 0 would return 0, a $value of 1 would return 255. This map_color statement says: "The interval [0, 255] is to be 100% of the color range we want to map [0, 1] onto"

  Another example:

  $value = .5;
  $result = map_color($value : 0, 255, 0 : 50, 50);

  In this case we'll spend 50% on the interval [0, 255] and 50% on the interval [255, 0] so a value of 0 or 1 will give us back 0 whereas a value of .5 will give us 255.

  Finally, note that there will always be one less percentage value than there were color values. This is because the percentage values indicate how much of the range will be used up between two colors.

  text_intersect(text, origin, $height, $thickness, point) - this function allows the use of a string of text as a trapping region (similar to what we describe here).

  This is basically a fun or experimental function and at the moment it only supports lower case letters, upper case letters and spaces.

  If you call text_intersect and get back a value of -1 then the supplied point does not interesect the text string, a value between 0 and 1 indicates that the point does intersect the text with zero meaning "right on the text" whereas one meaning "just on the edge of the text". This makes the use of gamma correction for 3D effects easy to accomplish, for example.

  The 'origin' is the starting point of the text, the 'height' is the height of the text, the 'thickness' is the thickness of the letters and 'point' is the point to be tested to see if it falls within the boundary of the text string.