A value transformer function can be supplied as a parameter to any method that supports a value transformer function, such as the Uize.map static method. Consider the following example...

EXAMPLE

function cubed (value) {
  return value * value * value;
}

var myValuesCubed = Uize.map (myValues,cubed);

The Uize.map method accepts a value and key transformer for its first parameter and a source array as its second. It iterates through all the elements of the source array, calling the Value and Key Transformer for each element. With the transformed element values returned by the value and key transformer, the method populates a new array.

In this example we are supplying a value transformer in place of a value and key transformer (see Using a Value Transformer in Place of a Value and Key Transformer), which just means that the additional key / index information for the elements will be ignored. The variable myValuesCubed, in this case, will contain the cubes of all the values in the myValues source array.

The value input parameter for a value transformer function can be named anything - it does not need to be named value. Consider the following example...

EXAMPLE

function cubed (toCube) {
  return toCube * toCube * toCube;
}

In the above example, our value parameter is named toCube.

A Curve Function is a specialized kind of value transformer whose input value is expected to be a floating point number in the range of 0 to 1, and where the returned transformed value should also be a floating point number in the range of 0 to 1.

EXAMPLE

Uize.Fade.Factory.fade (scrollTo,[0,0],[0,200],800,{curve:Uize.Curve.easeInOutPow (4)});

In the above example, the vertical scroll position of a browser window is being animated using the Uize.Fade.Factory.fade method of the Uize.Fade.Factory module. A curve function (which is a value transformer) is being created using the statement Uize.Curve.easeInOutPow (4), and this curve is being supplied to the Uize.Fade.Factory.fade method so that the animation isn't completely linear and lifeless - some non-linearity adds physical realism to the animation. The curve function is being used to bend / distort a 0 to 1 floating point number into a different 0 to 1 floating point number.

A value matcher is a specialized kind of value transformer that transforms a value to a boolean value.

EXAMPLE

function isOnlyWhitespace (value) {
  return /^\s*$/.test (value);
}

In the above example, the function isOnlyWhitespace returns a boolean value, indicating whether or not the input value is a string containing only whitespace characters (such as spaces and tabs). The fact that it always returns a value true or false makes it a value matcher (by the very definition of a value matcher).

A value conformer is a specialized kind of value transformer that transforms a value so that it conforms to certain criteria.

EXAMPLE

function limitStringLengthTo100Chars (sourceStr) {
  return sourceStr.length > 100 ? sourceStr.slice (0,100) : sourceStr;
}

In the above example, the limitStringLengthTo100Chars function is a value conformer that conforms a string value so that it can never be more than a hundred characters in length. It does this by using the String object's slice instance method, chopping off any characters beyond the first hundred.

The Uize.Fade class supports a value transformer with its curve state property.

Additionally, any of the factory methods that create instances of the Uize.Fade class will also support value transformers for the curve fade property. Examples of such factory methods are the Uize.Fade.Factory.fade, Uize.Fade.Factory.fadeMethod, Uize.Fade.Factory.fadeProperty, and Uize.Fade.Factory.fadeProperties methods implemented in the Uize.Fade.Factory module, as well as the Uize.Fx.fadeStyle and Uize.Fx.fadeStyleAcrossNodes methods of the Uize.Fx module.

For a more in-depth discussion of curve functions, see the section Curve Functions Are Specialized Value Transformers.

The Uize.Str.Lines.modify static method of the Uize.Str.Lines module supports a value transformer for the line modifier that processes each line of a multi-line string.

EXAMPLE

function limitStringLengthTo100Chars (sourceStr) {
  return sourceStr.length > 100 ? sourceStr.slice (0,100) : sourceStr;
}

Uize.Str.Lines.modify (multiLineStr,limitStringLengthTo100Chars);

In the above example, the Uize.Str.Lines.modify method is using the limitStringLengthTo100Chars value transformer to limit the length of all lines in a multi-line string to a maximum of a hundred characters - lines that are longer than a hundred characters in length will be truncated so that the extra characters are discarded.

A value transformer can always be used in place of a value and key transformer.

In such cases, the key that is supplied as the second parameter to the Value Transformer that is only expecting a single parameter will simply be ignored - the transformed value that it returns will only be influenced by the value and not the key.

2.3.3.1. The Uize.map Method

2.3.3.2. The Uize.Array.Sort.sortBy Method

Uize.Array.Sort.sortBy (dateStrings,function (value) {return +(new Date (value))});

There is no limit to the kinds of values that can be transformed by a value transformer.

While an input value for a Value Transformer is likely to be a simple type value, such as a number or a string, there is no saying that an input value can't also be an array or an object. Consider the following example...

EXAMPLE

function computeArea (value) {
  return value.width * value.height;
}

var
  rects = [
    {width:5,height:10},
    {width:1.4,height:5},
    {width:3,height:4}
  ],
  rectAreas = Uize.map (rects,computeArea)
;

In the above example, the computeArea function defines a value transformer that transforms an input value that is expected to be an object with width and height properties, into an area value that is computed as the product of the width and height properties. This value transformer is then supplied to the Uize.map method, which is used to produce an array containing the areas computed from the rectangle objects inside the rects array. After the above code has been executed, the statement alert (rectAreas) would display the text "50,7,12" in the alert dialog.

A value matcher function can be supplied as a parameter to any method that supports a value matcher function, such as the Uize.Str.Lines.removeMatching static method of the Uize.Str.Lines module. Consider the following example...

EXAMPLE

function isOnlyWhitespace (value) {
  return /^\s*$/.test (value);
}

myString = Uize.Str.Lines.removeMatching (myString,isOnlyWhitespace);

The Uize.Str.Lines.removeMatching method accepts a multi-line string (containing zero or more linebreaks) for its first parameter and a matcher function as its second. It iterates through all the lines of the specified multi-line string, calling the Value Matcher Function for each line. Depending on the boolean value that is returned by the matcher, the method will either remove or retain the line.

The variable myString, in this case, will contain only the lines of the source multi-line string that have at least one non-whitespace character - lines containing only whitespace are matched by the isOnlyWhitespace matcher function and are removed by the Uize.Str.Lines.removeMatching method.

A value validator is a specialized kind of value matcher that transforms a value to a boolean value, indicating whether or not the input value is valid according to certain criteria.

A value validator is no more than a value matcher, where the implication of a value not being matched by the matcher is that the value is not valid.

Some of the static methods of the Uize.Str.Lines module support a value matcher.

3.4.1.1. Uize.Str.Lines.removeMatching

myString = Uize.Str.Lines.removeMatching (
  myString,
  function (value) {return /^\s*$/.test (value)
};

3.4.1.2. Uize.Str.Lines.retainMatching

myString = Uize.Str.Lines.retainMatching (
  myString,
  function (value) {return /\S/.test (value)
};

A value conformer function can be supplied as a parameter to any method that supports a value transformer function, such as the Uize.map static method. Consider the following example...

EXAMPLE

Uize.map (myNumbersArray,Math.round,false);

In the above example, the Math.round static method of JavaScript's built-in Math object is being used as a value conformer with the Uize.map method in order to conform all the number values in an array to integer values. The third parameter of the Uize.map method specifies the target for the mapped values, where the value false indicates that the values should not be populated into a new array but should replace the values in the source array.

4.2.1.1. Conformers for State Properties

function conformToRange0to100 (value) {
  return Uize.constrain (value,0,100);
}

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:conformToRange0to100,
    value:0
  }
});