SHIP:Sail:towards

Function	Returns	Introduced	Description
towards	Float/Integer	v5.0.207	Adjusts a number by a percentage in a range towards another number.

See Also:

• Sail Home
• Sail Functions
• Sail Numeric Functions
• mapRange

Prototypes

Float towards(Float percent, Float current, Float target[, Float doneWithin]);

Integer towards(Float percent, Integer current, Integer target[, Integer doneWithin]);

Parameters/Return Value

Parameter	Data Type	Description
percent	Float	Percent to move current towards target
current	Float Integer	Current value
target	Float Integer	Target ending value
doneWithin	Float Integer	(optional) When the result would be less than or equal to this distance from the target, the target value is returned. Defaults to 1 (or 1.0f) if not supplied.
Return	Float Integer	A new number "towards" the target

Detailed Description

The towards function moves a current numeric value towards a target value by a percentage.

The function is very useful in moving objects (e.g. gauge needles, sliders, boxes/images) in a fluid manner from their current positions to a target position. For example, when a slider needs to move from pixel position 55 to 85, rather than just assign the slider's position directly to 85 on a change, one can create a much more fluid movement using towards.

The structure of this would use a timer within the object (such as a slider box):

   variable Integer target
   box
       timer oneshot=true value=1 period=1 autoreload=true enabled=false
           listener listeningto=timer.alarm condition=timer.alarm
               script
                   box.ol        = towards(0.33f, box.ol, target);
                   timer.alarm   = false;
                   timer.enabled = (target != box.ol);
           listener listeningto=target
                   timer.enabled = (target != box.ol);

The doneWithin Parameter and the Float Variant of the Function

In the floating point version of this function (where any of the 3 parameters current, target, and/or doneWithin are supplied as floating point values), the returned value will asymptotically approach the target.

By specifying the doneWithin parameter, when the returned value would be less than or equal to a doneWithin distance from the target, the target value is returned.

For example, continuously moving 25% towards a target number using floating point values:

   Float f = 1.0f;
   ...
   (repeated) f = towards(0.25f, f, 5.0f, 0.1f);

Will, upon repetition of the formula, adjust f by 25% towards the target of 5.0 until is within 0.1 of 5.0, at which point 5.0 will be returned.

doneWithin, if not supplied, defaults to 1.0f in the floating point variant of the function.

The doneWithin Parameter and the Integer Variant of the Function

When using integer values, an infinite loop possibility exists where the current never (after repeated assigns) reaches the target.

For example, 33% of the distance between 0 and 1 is always 0 from an integer perspective, and so repeated calls with these parameters will never have the current reach the target.

In a related example, 25% of the distance between 0 and 2 is always 0 from an integer perspective, again causing a potential infinite loop where the current value never moves at all.

There are 2 mechanisms that prevent these behaviors.

First, the remaining distance to the target is internally calculated and truncated. Therefore any fractional amount will cause the current to move by at least 1. This mechanism handles both problematic scenarios above.

The doneWithin, if not supplied, defaults to 1 in the integer variant of the function, and is redundant with the remaining-distance truncation method. However, a designer may choose a greater value to "snap to" a target when within a larger distance.

Examples

Example	Result	Notes
towards(0.25f,0,4);	1	25% from 0 to 4 is 1.
towards(0.25f,4,0);	3	25% from 4 to 0 is 3.
towards(0.25f,-4,4);	-2	25% from -4 to +4 is 2.
towards(0.25f,3,4);	4	Integer form of function, remaining distance (0.75) is truncated so the return value is 4.
towards(0.25f,3,4.0f,0.25f);	3.25f	Floating point form of function
towards(0.75f,3,4.0f,0.25f);	4.00f	Floating point form of function; result is 3.75 but is within the 0.25f snapWithin range so result is target.