Utils – amCharts 4 Documentation

Type module

Sources

Items from Utils can be imported/included and used via following ways.

/**
 * --------------------------------------------------------
 * Import via main package: core.ts
 * Access items like: am4core.utils.myVariable
 *                    am4core.utils.myFunction()
 * --------------------------------------------------------
 */
import * as am4core from "@amcharts/amcharts4";

/**
 * --------------------------------------------------------
 * Import via: Utils.ts
 * Access items like: $utils.myVariable
 *                    $utils.myFunction()
 * --------------------------------------------------------
 */
import * as $utils from "@amcharts/amcharts4/Utils";

/**
 * --------------------------------------------------------
 * Include via "core.js"
 * Access items like: am4core.utils.myVariable
 *                    am4core.utils.myFunction()
 * --------------------------------------------------------
 */

Variables

urlRegexp #	Type `RegExp` Default `/^([a-zA-Z][a-zA-Z0-9+.-]:)?(?:(//)([^@]+@)?([^/?#:])(:[0-9]+)?)?([^?#])(?[^#])?(#.*)?$/`

urlRegexp
#

Type RegExp

Default /^([a-zA-Z][a-zA-Z0-9+.-]*:)?(?:(//)([^@]+@)?([^/?#:]*)(:[0-9]+)?)?([^?#]*)(?[^#]*)?(#.*)?$/

Functions

anyToDate( value: `Date` \| `number` \| `string` ) #	Returns `Date` Converts anything to Date object.
anyToNumber( value: `Date` \| `number` \| `string` ) #	Returns `$type.Optional` < `number` > Tries converting any value to a number.
camelToDashed( str: `string` ) #	Returns `string` Converts camelCased text to dashed version: ("thisIsString" > "this-is-string")
capitalize( str: `string` ) #	Returns `string` Converts tring to uppercase. @todo Maybe make it better
copyProperties( source: `object`, target: `object`, keys: `Array` < `string` > ) #	Returns `void` Copies all properties of one object to the other, omitting undefined. @todo Maybe consolidate with utils.copy?
documentPointToSprite( point: `IPoint`, sprite: `Sprite` ) #	Returns `IPoint` Converts document-wide global coordinates to coordinates within specific `Sprite`.
documentPointToSvg( point: `IPoint`, svgContainer: `HTMLElement`, cssScale?: `number` ) #	Returns `IPoint` Converts global document-wide coordinates to coordinates within SVG element.
escapeForRgex( value: `string` ) #	Returns `string` Escapes string so it can safely be used in a Regex.
fitNumber( value: `number`, min: `number`, max: `number` ) #	Returns `number` Fits the number into specific `min` and `max` bounds.
fitNumberRelative( value: `number`, min: `number`, max: `number` ) #	Returns `number` Fits the number into specific `min` and `max` bounds. If the value is does not fit withing specified range, it "wraps" around the values. For example, if we have input value 10 with min set at 1 and max set at 8, the value will not fit. The remainder that does not fit (2) will be added to `min`, resulting in 3. The output of regular `fitNumber()` would return 8 instead.
get12Hours( hours: `number`, base?: `number` ) #	Returns `number` Returns 12-hour representation out of the 24-hour hours.
getBaseURI() #	Returns `string`
getDayFromWeek( week: `number`, year: `number`, weekday: `number`, utc: `boolean` ) #	Returns `number` Returns a year day out of the given week number.
getMonthWeek( date: `Date`, utc: `boolean` ) #	Returns `number` Returns a week number in the month.
getPixelRatio() #	Returns `number` Returns pixel ratio of the current screen (used on retina displays).
getTimeZone( date: `Date`, long: `boolean`, savings: `boolean`, utc: `boolean` ) #	Returns `string` Returns a string name of the tome zone.
getWeek( date: `Date`, utc: `boolean` ) #	Returns `number` Returns week number for a given date. @todo Account for UTC
getYearDay( date: `Date`, utc: `boolean` ) #	Returns `number` Returns a year day. @todo Account for UTC
isIE() #	Returns `boolean` Detects MSIE.
isNotEmpty( value: `$type.Optional` < `string` > ) #	Returns `value` Checks if value is not empty (undefined or zero-length string).
ltrim( str: `string` ) #	Returns `string` Removes whitespace from beginning of the string.
numberToString( value: `number` ) #	Returns `string` Converts numeric value into string. Deals with large or small numbers that would otherwise use exponents.
padString( value: `any`, len: `number`, char: `string` ) #	Returns `string` Pads a string with additional characters to certain length.
plainText( text: `string` ) #	Returns `string` Removes new lines and tags from a string.
random( chars: `number` ) #	Returns `string` Returns a random number between `from` and `to`.
reverseString( str: `string` ) #	Returns `string` Reverses string.
rtrim( str: `string` ) #	Returns `string` Removes whitespace from end of the string.
softCopyProperties( source: `object`, target: `object`, keys: `Array` < `string` > ) #	Returns `void` Copies all properties of one object to the other, omitting undefined, but only if property in target object doesn't have a value set. @todo Maybe consolidate with utils.copy?
splitTextByCharCount( text: `string`, maxChars: `number`, fullWords?: `boolean`, rtl?: `boolean`, fullWordFallback?: `boolean` ) #	Returns `string[]` Splits the text into multiple lines, respecting maximum character count. Prioretizes splitting on spaces and punctuation. Falls back on splitting mid-word if there's no other option.
spritePointToDocument( point: `IPoint`, sprite: `Sprite` ) #	Returns `IPoint` Converts coordinates within `Sprite` to global document coordinates.
spritePointToSprite( point: `IPoint`, sprite: `Sprite`, toSprite: `Sprite` ) #	Returns `IPoint` Converts coordinates of one sprite to another.
spritePointToSvg( point: `IPoint`, sprite: `Sprite` ) #	Returns `IPoint` Converts coordinates within `Sprite` to coordinates relative to the whole SVG element.
spriteRectToSvg( rect: `IRectangle`, sprite: `Sprite` ) #	Returns `IRectangle` Converts a rectangle expressed in `Sprite` coordinates to SVG coordinates.
stringify( value: `any` ) #	Returns `string` Converts any value into its string representation.
stripHash( url: `string` ) #	Returns `string` Removes target from url
stripTags( text: `string` ) #	Returns `string` Strips all tags from the string.
svgPointToDocument( point: `IPoint`, svgContainer: `HTMLElement` ) #	Returns `IPoint` Converts SVG coordinates to global document-wide coordinates.
svgPointToSprite( point: `IPoint`, sprite: `Sprite` ) #	Returns `IPoint` Converts SVG element coordinates to coordinates within specific `Sprite`.
svgRectToSprite( rect: `IRectangle`, sprite: `Sprite` ) #	Returns `IRectangle` Converts a rectangle expressed in SVG element coordinates to coordinates within specific `Sprite`.
trim( str: `string` ) #	Returns `string` Removes whitespace from beginning and end of the string.
truncateWithEllipsis( text: `string`, maxChars: `number`, ellipsis: `string`, fullWords?: `boolean`, rtl?: `boolean` ) #	Returns `string` Truncates the text to certain character count. Will add ellipsis if the string is truncated. Optionally, can truncate on full words only. For RTL support, pass in the fifth parameter as `true`.
unquote( str: `string` ) #	Returns `string` Removes quotes from the string.
used( value: `A` ) #	Returns `void` Marks a value as being used (e.g. because the value has side effects).

anyToDate(

value: Date | number | string

)

Returns Date

Converts anything to Date object.

anyToNumber(

value: Date | number | string

)

Returns $type.Optional < number >

Tries converting any value to a number.

camelToDashed(

str: string

)

Returns string

Converts camelCased text to dashed version:

("thisIsString" > "this-is-string")

capitalize(

str: string

)

Returns string

Converts tring to uppercase.

@todo Maybe make it better

copyProperties(

source: object,
target: object,
keys: Array < string >

)

Returns void

Copies all properties of one object to the other, omitting undefined.

@todo Maybe consolidate with utils.copy?

documentPointToSprite(

point: IPoint,
sprite: Sprite

)

Returns IPoint

Converts document-wide global coordinates to coordinates within specific Sprite.

documentPointToSvg(

point: IPoint,
svgContainer: HTMLElement,
cssScale?: number

)

Returns IPoint

Converts global document-wide coordinates to coordinates within SVG element.

escapeForRgex(

value: string

)

Returns string

Escapes string so it can safely be used in a Regex.

fitNumber(

value: number,
min: number,
max: number

)

Returns number

Fits the number into specific min and max bounds.

fitNumberRelative(

value: number,
min: number,
max: number

)

Returns number

Fits the number into specific min and max bounds.

If the value is does not fit withing specified range, it "wraps" around the values.

For example, if we have input value 10 with min set at 1 and max set at 8, the value will not fit. The remainder that does not fit (2) will be added to min, resulting in 3.

The output of regular fitNumber() would return 8 instead.

get12Hours(

hours: number,
base?: number

)

Returns number

Returns 12-hour representation out of the 24-hour hours.

getBaseURI()

Returns string

getDayFromWeek(

week: number,
year: number,
weekday: number,
utc: boolean

)

Returns number

Returns a year day out of the given week number.

getMonthWeek(

date: Date,
utc: boolean

)

Returns number

Returns a week number in the month.

getPixelRatio()

Returns number

Returns pixel ratio of the current screen (used on retina displays).

getTimeZone(

date: Date,
long: boolean,
savings: boolean,
utc: boolean

)

Returns string

Returns a string name of the tome zone.

getWeek(

date: Date,
utc: boolean

)

Returns number

Returns week number for a given date.

@todo Account for UTC

getYearDay(

date: Date,
utc: boolean

)

Returns number

Returns a year day.

@todo Account for UTC

isIE()

Returns boolean

Detects MSIE.

isNotEmpty(

value: $type.Optional < string >

)

Returns value

Checks if value is not empty (undefined or zero-length string).

ltrim(

str: string

)

Returns string

Removes whitespace from beginning of the string.

numberToString(

value: number

)

Returns string

Converts numeric value into string. Deals with large or small numbers that would otherwise use exponents.

padString(

value: any,
len: number,
char: string

)

Returns string

Pads a string with additional characters to certain length.

plainText(

text: string

)

Returns string

Removes new lines and tags from a string.

random(

chars: number

)

Returns string

Returns a random number between from and to.

reverseString(

str: string

)

Returns string

Reverses string.

rtrim(

str: string

)

Returns string

Removes whitespace from end of the string.

softCopyProperties(

source: object,
target: object,
keys: Array < string >

)

Returns void

Copies all properties of one object to the other, omitting undefined, but only if property in target object doesn't have a value set.

@todo Maybe consolidate with utils.copy?

splitTextByCharCount(

text: string,
maxChars: number,
fullWords?: boolean,
rtl?: boolean,
fullWordFallback?: boolean

)

Returns string[]

Splits the text into multiple lines, respecting maximum character count.

Prioretizes splitting on spaces and punctuation. Falls back on splitting mid-word if there's no other option.

spritePointToDocument(

point: IPoint,
sprite: Sprite

)

Returns IPoint

Converts coordinates within Sprite to global document coordinates.

spritePointToSprite(

point: IPoint,
sprite: Sprite,
toSprite: Sprite

)

Returns IPoint

Converts coordinates of one sprite to another.

spritePointToSvg(

point: IPoint,
sprite: Sprite

)

Returns IPoint

Converts coordinates within Sprite to coordinates relative to the whole SVG element.

spriteRectToSvg(

rect: IRectangle,
sprite: Sprite

)

Returns IRectangle

Converts a rectangle expressed in Sprite coordinates to SVG coordinates.

stringify(

value: any

)

Returns string

Converts any value into its string representation.

stripHash(

url: string

)

Returns string

Removes target from url

stripTags(

text: string

)

Returns string

Strips all tags from the string.

svgPointToDocument(

point: IPoint,
svgContainer: HTMLElement

)

Returns IPoint

Converts SVG coordinates to global document-wide coordinates.

svgPointToSprite(

point: IPoint,
sprite: Sprite

)

Returns IPoint

Converts SVG element coordinates to coordinates within specific Sprite.

svgRectToSprite(

rect: IRectangle,
sprite: Sprite

)

Returns IRectangle

Converts a rectangle expressed in SVG element coordinates to coordinates within specific Sprite.

trim(

str: string

)

Returns string

Removes whitespace from beginning and end of the string.

truncateWithEllipsis(

text: string,
maxChars: number,
ellipsis: string,
fullWords?: boolean,
rtl?: boolean

)

Returns string

Truncates the text to certain character count.

Will add ellipsis if the string is truncated. Optionally, can truncate on full words only.

For RTL support, pass in the fifth parameter as true.

unquote(

str: string

)

Returns string

Removes quotes from the string.

used(

value: A

)

Returns void

Marks a value as being used (e.g. because the value has side effects).