vega-format

String formatting utilities for number and date values.

API Reference

• Number Format Locale
• Time Format Locale
• Combined Locale

Number Format Locale

# vega.numberFormatLocale(definition) <>

Returns a locale object with methods for number formatting, based on the provided definition. The definition argument must match the format expected by d3-format. For examples of definition files for a variety of languages, see the d3-format locale collection.

# locale.format([specifier]) <>

Returns a function that takes a number as input and returns a formatted string. If a string-valued format specifier is provided, it must follow the d3-format syntax. The returned function is akin to d3-format's format method.

# locale.formatPrefix(specifier, value) <>

Returns a function that takes a number as input and returns a formatted string, with a fixed SI prefix anchored at the provided value. The string-valued format specifier must follow the d3-format syntax. The returned function is akin to d3-format's formatPrefix method.

# locale.formatFloat([specifier]) <>

Returns a function that takes a number as input and returns a formatted string. This method is similar to the format method, except that if the specifier does not provide a precision, the returned formatter will use a variable (floating) precision depending on the number of significant digits. Vega uses this method to provide improved formatting for values plotted on a logarithmic scale.

# locale.formatSpan(start, stop, count[, specifier]) <>

Returns a function that takes a number as input and returns a formatted string appropriate for a specified span of numbers defined by start and stop values and a count of values in the range. Based on these values, the method will attempt to find an appropriate precision. For example, to format 20 numbers on the range [0, 10], a precision of 0.1 ('0.1f') will be used. An optional specifier can be used to further customize the format; if the specifier includes a numeric precision that value will override the span-based precision.

# vega.numberFormatDefaultLocale([definition]) <>

Get or set the default locale for number formatting. If no arguments are provided, returns the current default locale. Otherwise, sets the default locale based on the provided definition, and returns the resulting locale object. The input definitions should be of the same type accepted by the numberFormatLocale method.

# vega.resetNumberFormatDefaultLocale() <>

Resets the default locale for number formatting and returns the resulting locale object. The new default number locale for Vega will match the current default locale for the underlying d3-format library.

Time Format Locale

# vega.timeFormatLocale(definition) <>

Returns a locale object with methods for time formatting, based on the provided definition. The definition argument must match the format expected by d3-time-format. For examples of definition files for a variety of languages, see the d3-time-format locale collection.

# locale.timeFormat([specifier]) <>

Returns a function that takes a date or timestamp as input and returns a formatted string in the local timezone. If a string-valued format specifier is provided, it must follow the d3-time-format syntax. The returned function is akin to d3-time-format's timeFormat method.

If an object-valued specifier is provided, a multi-format function will be generated, which selects among different format specifiers based on the granularity of the input date value (that is, values residing on a year, month, date, etc., boundary can all be formatted differently). The input object should use proper time unit strings for keys. If no time format specifier is provided, a default multi-format function is returned, equivalent to using the following specifier:

{
  "year": "%Y",
  "quarter": "%B",
  "month": "%B",
  "week": "%b %d",
  "date": "%a %d",
  "hours": "%I %p",
  "minutes": "%I:%M",
  "seconds": ":%S",
  "milliseconds": ".%L"
}

If an input specifier object omits any of these key values, a default value will be used. Note that for this method the "date" and "day" units are interchangeable; if both are defined the "date" entry take precedence.

# locale.utcFormat([specifier]) <>

Returns a function that takes a date or timestamp as input and returns a formatted string in Coordinated Universal Time (UTC). If a string-valued format specifier is provided, it must follow the d3-time-format syntax. The returned function is akin to d3-time-format's utcFormat method.

This method also accepts object-valued specifiers for creating multi-format functions. If no argumennts are provided, a defualt multi-format function will be returned. For more details, see the timeFormat method documentation.

# locale.timeParse(specifier) <>

Returns a function that takes a string as input and returns a date. The string-valued format specifier must follow the d3-time-format syntax. The returned function is akin to d3-time-format's timeParse method.

# locale.utcParse(specifier) <>

Returns a function that takes a string as input and returns a date in Coordinated Universal Time (UTC). The string-valued format specifier must follow the d3-time-format syntax. The returned function is akin to d3-time-format's utcParse method.

# vega.timeFormatDefaultLocale([definition]) <>

Get or set the default locale for time formatting. If no arguments are provided, returns the current default locale. Otherwise, sets the default locale based on the provided definition, and returns the resulting locale object. The input definitions should be of the same type accepted by the timeFormatLocale method.

# vega.resetTimeFormatDefaultLocale() <>

Resets the default locale for time formatting and returns the resulting locale object. The new default time locale for Vega will match the current default locale for the underlying d3-time-format library.

Combined Locale

Combined locale objects provide a convenient abstraction for both number and time formatting methods defined on a single object. A combined locale object contains the methods of both a number format locale object and a time format locale object.

# vega.locale(numberDefinition, timeDefinition) <>

Returns a combined locale object with methods for both number and time formatting, based on the provided numberDefinition and timeDefinition. The definition arguments must match the format expected by d3-format and d3-time-format. If either argument is null or unspecified, the corresponding default locale is used instead. For examples of definition files for a variety of languages, see the d3-format locale collection and d3-time-format locale collection.

# vega.defaultLocale([numberDefinition, timeDefinition]) <>

Get or set the default locale for both number and time formatting. If no arguments are provided, returns the current default locale. Otherwise, sets the default locales based on the provided numberDefinition and timeDefinition, and returns the resulting combined locale object. The input definitions should be of the same type accepted by the locale method.

# vega.resetDefaultLocale() <>

Resets the default locale for both number and time formatting and returns the resulting comgined locale object. The new default locales for Vega will match the current default locales for the underlying d3-format and d3-time-format libraries.