keta – Docs – Module: Unit

A filter using SI prefixes to format numeric values.

The filter takes a couple of parameters to configure it. unit defines the unit as string to append to formatted value (e.g. 'W', defaults to empty string). precision defines the number of digits to appear after the decimal point as integer (e.g. 2, defaults to 0). precisionRanges defines used precision in a more flexible way by defining an array of precisions with min (included) and/or max (excluded) value. precisionExcludeIntegers defines if integers should be excluded from precision. precisionExclude defines concrete values which are excluded from precision. isBytes is a boolean flag tom specify if the given number is bytes and therefor 1024-based (defaults to false). separate is a boolean flag (defaults to false) which defines whether to return a single string or an object with separated values numberFormatted (String), numberRaw (Number) and unit (String).

If precisionRanges is set to:

[
    {max: 1000, precision: 0},
    {min: 1000, precision: 1}
]

If precisionExclude is set to:

[0.123456, 100.123456]

values that are 0.123456 or 100.123456 wouldn't be cutted by precision.

numeric values which are less than 1000 are formatted with a precision of 0, as numeric values equal or greater than 1000 are formatted with a precision of 1.

If separate is set to true the filter returns an object in the following manner if for instance German is the current locale:

{
    numberFormatted: '1,546',
    numberRaw: 1.546,
    unit: 'kW'
}

Author:

Marco Lehmann <marco.lehmann (at) kiwigrid.com>

Copyright:

Kiwigrid GmbH 2014-2015

Source:

filters/unit.js, line 3

Examples

{{ 1234.56 | ketaUnit:{unit: 'W', precision: 1, isBytes: false} }}

Number: {{ (1234.56 | ketaUnit:{unit: 'W', precision: 1, isBytes: false, separate:true}).numberFormatted }}
Unit: {{ (1234.56 | ketaUnit:{unit: 'W', precision: 1, isBytes: false, separate:true}).unit }}

angular.module('exampleApp', ['keta.filters.Unit'])
    .controller('ExampleController', function($scope) {

        // use unit filter to return formatted number value
        // $scope.value equals string '1.2 kW'
        $scope.value = $filter('ketaUnit')(1234.56, {
            unit: 'W',
            precision: 1,
            isBytes: false
        });

        // use unit filter for integers that shouldn't be cutted by precision
        // $scope.valuePrecisionIntegersExcluded equals string '123 W'
        $scope.valuePrecisionIntegersExcluded = $filter('ketaUnit')(123, {
            unit: 'W',
            precision: 2,
            precisionExcludeIntegers: true
        });

        // use unit filter for values that shouldn't be cutted by precision
        // $scope.valuePrecisionExcluded equals string '0.123456 W'
        $scope.valuePrecisionExcluded = $filter('ketaUnit')(0.123456, {
            unit: 'W',
            precision: 2,
            precisionExclude: [0.123456]
        });

        // use unit filter to return object for number formatting
        // $scope.valueSeparated equals object {numberFormatted: '1.2', numberRaw: 1.2, unit: 'kW'}
        // as numberFormatted is locale-aware, numberRaw remains a real number to calculate with
        // e.g. for German numberFormatted would be formatted to '1,2' and numberRaw would still be 1.2
        $scope.valueSeparated = $filter('ketaUnit')(1234.56, {
            unit: 'W',
            precision: 1,
            isBytes: false,
            separate: true
        });

        // use unit filter with precision ranges
        // for the example below all values which are less than 1000 are formatted with a precision of 0
        // and all values equal or greater than 1000 are formatted with a precision of 1
        $scope.valueRanges = $filter('ketaUnit')(1234.56, {
            unit: 'W',
            precision: 1,
            precisionRanges: [
                {max: 1000, precision: 0},
                {min: 1000, precision: 1}
            ],
            isBytes: false
        });

    });