VEGAS JS Namespace: strings

The core.strings package is a modular JavaScript library that provides extra String methods.

Author:

Marc Alcaraz

License:

MPL 2.0 / GPL 2.0 / LGPL 2.1

Members

<static> latins

The object to access the translation table or to change the mapping. This object is used in the latinize function.

Note: This object is only available in ES6 with a module exportation. We don't include this function in the vegas.js and vegas.min.js libraries

Example

import { latins } from './core/strings/latins.js' ;
latins['Ω'] = 'O';

Methods

between(source)

Converts a hyphenated string to a camelcased string.

Parameters:

Name	Type	Description
`source`	string	The string reference to transform.

Returns:

The new extracted string.

Example

trace( between("<b>hello</b>" , "<b>" , "</b>" ) ) ; // hello
trace( between("hello {world}" , "{" , "}" ) ) ; // world

camelCase(source)

Converts a hyphenated string to a camelcased string.

Parameters:

Name	Type	Description
`source`	string	The string reference to camelcase.

Returns:

The camelcased string.

Example

trace( camelCase("hello-world" ) ) ; // helloWorld

capitalize(source)

Converts the first letter of each word in a string to uppercase.

Parameters:

Name	Type	Description
`source`	string	The string reference to transform.

Returns:

The capitalized string.

Example

trace( capitalize( "hello world" ) ) ; // Hello World

center(source [, size] [, separator=])

Returns the center string representation of the specified string value.

Parameters:

Name	Type	Argument	Default	Description
`source`	string			The string reference to center.
`size`	number	<optional>	0	The number of character to center the String expression.
`separator=`	string	<optional>		The optional separator character use before and after the String to center.

Returns:

The center expression of the specified string.

Example

trace( '<' + center("hello world", 0)  + '>' ) ; // <hello world>
trace( '<' + center("hello world", 20) + '>' ) ; // <    hello world     >
trace( '<' + center("hello world", 20, "_" ) + '>'  )  ; // <____hello world_____>

clean(source)

Removes all extraneous whitespace from a string and trims it.

Parameters:

Name	Type	Description
`source`	string	The string reference to clean.

Returns:

The cleaned string.

Example

trace( clean("   hello world \n\n" ) ) ; // hello world

compare(str1, str2 [, strict])

Compares two strings, the default comparaison algorithm use an ascending alphabetic order with minuscule weighting less than majuscule.

Parameters:

Name	Type	Argument	Default	Description
`str1`	string			The first string to compare with the second string
`str2`	string			Thesecond string to compare with the first string
`strict`	boolean	<optional>	false	This flag indicates if the function take into account the string case, default to false

Returns:

An integer value :

0 if the two strings are considered equals
-1 if the first string is considered smaller (lower) than the second string
1 if the first string is considered bigger (higher) than the second string

Example

var s0 = "HELLO";
var s1 = "hello";
var s2 = "welcome";
var s3 = "world";

trace( compare( s1, s2 ) ); //-1
trace( compare( s2, s1 ) ); //1
trace( compare( s1, s3 ) ); //1
trace( compare( s1, s1 ) ); //0
trace( compare( s1, s0 ) ); //0
trace( compare( s1, s0, true ) ); //-1
trace( compare( s0, s1, true ) ); //1

endsWith(source, value)

Determines wether the end of a string matches the specified value.

Parameters:

Name	Type	Description
`source`	string	The string reference to check.
`value`	string	The value to find in end in the source.

Returns:

true if the value is find in first.

Example

Basic usage

trace( endsWith( "hello world", "world" ) ); //true
trace( endsWith( "hello world", "hello" ) ); //false

fastformat(pattern, args)

Quick and fast format of a string using indexed parameters only.

Usage :

fastformat( pattern:String, ...args:Array ):String
fastformat( pattern:String, [arg0:,arg1:,arg2:*, ...] ):String

Parameters:

Name	Type	Argument	Description
`pattern`	string		The String pattern expression to format.
`args`	string	<repeatable>	A serie of strings values or of arrays of strings to fill the pattern expression.

See:

core.strings.format

Returns:

The formatted expression.

Example

trace( fastformat( "hello {0}", "world" ) ); // "hello world"
trace( fastformat( "hello {0} {1} {2}", [ "the", "big", "world" ] ) ); // "hello the big world"
trace( fastformat( "hello {0} {1} {2}", [ "the", "big" ] , "world" ) ); // "hello the big world"

fastformatDate( [date] [, separator])

Returns the string representation of the specific date with the format "yyyy-mm-dd".

Parameters:

Name	Type	Argument	Default	Description
`date`	Date	<optional>	null	The date object to format (default the current Date if the argument is null).
`separator`	string	<optional>	-	The default separator of the format expression.

Returns:

The string representation of the specific date with the format "yyyy-mm-dd".

Example

trace( fastformatDate(new Date(2016,5,12)) ) ; // "2016-06-12"
trace( fastformatDate(new Date(2016,5,12),"/") ) ; // "2016/06/12"

format(pattern, args)

Format a string using indexed or named parameters.

Usage :

format( pattern, ...args )
format( pattern, [arg0,arg1,arg, ...] )
format( pattern, [arg0:*,arg1,arg2, ...], ...args )
format( pattern, {name0:value0,name1:value1,name2:value2, ...} )
format( pattern, {name0:value0,name1:value1,name2:value2, ...}, ...args )

Parameters:

Name	Type	Description
`pattern`	string	The string expression to format.
`args`	string \| array \| Object	A serie of strings values or of arrays of strings or an Object to fill the pattern expression.

See:

core.strings.fastformat

Throws:

Error when a token is malformed.

Returns:

The formatted expression.

Example

trace( core.strings.format( "{0},{1},{2}" , "apples" , "oranges", "grapes" ) ) ; // apples,oranges,grapes
trace( core.strings.format( "{0},{1},{2}" , ["apples" , "oranges", "grapes"] ) ) ; // apples,oranges,grapes
trace( core.strings.format( "{path}{0}{name}{1}" , { name : "format" , path:"core.strings" } , "." , "()" ) ) ; // core.strings.format()

hyphenate(source)

Converts a camelcased string to a hyphenated string.

Parameters:

Name	Type	Description
`source`	string	The string reference to hyphenate.

Returns:

The hyphenated string.

Example

trace( hyphenate( "helloWorld" ) ) ; //"hello-world"

indexOfAny(source, anyOf [, startIndex] [, count])

Reports the index of the first occurrence in a string expression of any character in a specified array of Unicode characters.

Parameters:

Name	Type	Argument	Default	Description
`source`	string			The string reference to check.
`anyOf`	Array			The Array of Unicode characters to find in the String.
`startIndex`	number	<optional>	0	The init position of the search process.
`count`	number	<optional>	-1	The number of character positions to examine.

Returns:

the index of the first occurrence in this instance of any character in a specified array of Unicode characters.

Example

trace( indexOfAny( "hello world" , ["h","e","l"]) ) ; // 0
trace( indexOfAny( "hello world" , ["w","a","i","t"]) ) ; // 6
trace( indexOfAny( "hello world" , ["n","i"] ) ) ; // -1

insert(source [, index], value)

Inserts a specified instance of String at a specified index position in this instance.

Note :

if index >= source.length, we directly append the value to the end of the string.
if index == 0, we directly insert it to the begining of the string.
if index < 0, we directly insert but searching backwards from the source.length - index position.

Parameters:

Name	Type	Argument	Default	Description
`source`	string			The string reference to change.
`index`	number	<optional>	0	The position to insert the new characters.
`value`	string			The expression to insert in the source.

Returns:

the modified string expression.

Example

trace( insert("hello",  0, "a" ) ) ; // ahello
trace( insert("hello",  1, "a" ) ) ; // haello
trace( insert("hello", 10, "a" ) ) ; // helloa
trace( insert("hello", -1, "a" ) ) ; // helloa
trace( insert("hello", -2, "a" ) ) ; // hellao

lastIndexOfAny(source, anyOf [, startIndex] [, count])

Reports the index position of the last occurrence in this instance of one or more characters specified in a Unicode array.

Parameters:

Name	Type	Argument	Default	Description
`source`	string			The string reference to check.
`anyOf`	Array			The Array of Unicode characters to find in the String.
`startIndex`	number	<optional>		The init position of the search process (by default the length-1 of the source).
`count`	number	<optional>	-1	The number of character positions to check.

Returns:

the index position of the last occurrence in this instance of one or more characters specified in a Unicode array.

Example

trace( lastIndexOfAny( "hello world" , ["n","i"] ) ) ; // -1
trace( lastIndexOfAny( "hello world" , ["h","e","l"]) ) ; // 0
trace( lastIndexOfAny( "hello world" , ["l","e","h"]) ) ; // 9
trace( lastIndexOfAny( "hello world" , ["w","a","i","t"]) ) ; // 6
trace( lastIndexOfAny( "hello world" , ["d","r","a","w"]) ) ; // 10
trace( lastIndexOfAny( "hello world" , ["l"]) ) ; // 9
trace( lastIndexOfAny( "hello world" , ["l"] , 9 ) ) ; // 3
trace( lastIndexOfAny( "hello world" , ["w"] , 9 , 5 ) ) ; // 6

latinize(source)

Converts accents (diacritics) from strings to latin characters.

Note: This function is only available in ES6 with a module exportation. We don't include this function in the vegas.js and vegas.min.js libraries

Parameters:

Name	Type	Description
`source`	string	The string reference to latinize.

Returns:

The latinized string.

Example

import { latinize } from './core/strings/latinize.js' ;

trace( latinize('ỆᶍǍᶆṔƚÉ áéíóúýčďěňřšťžů') ) ; // 'ExAmPlE aeiouycdenrstzu'

pad(source, amount, char)

Apply character padding to a string.

The padding amount is relative to the string length, if you try to pad the string "hello" (5 chars) with an amount of 10, you will not add 10 spacing chars to the original string, but you will obtain ".....hello", exactly 10 chars after the padding.

A positive amount value will pad the string on the left (right align), and a negative amount value will pad the string on the right (left align).

Parameters:

Name	Type	Description
`source`	string	The string reference to pad.
`amount`	number	the amount of padding (number sign is the padding direction)
`char`		the character to pad with (default is space)

Examples

Basic usage

trace( "left  : [" + pad( "hello" , 8 )  + "]" ); //left  : [   hello]
trace( "right : [" + pad( "hello" , -8 ) + "]" ); //right : [hello   ]

Padding a list of names

//.....jerry
//....george
//....kramer
//.....helen

var seinfeld = [ "jerry", "george", "kramer", "helen" ];

var len = seinfeld.length ;
for( var i = 0 ; i<len ; i++ )
{
    trace( pad( seinfeld[i] , 10 , "." ) ) ;
}

repeat(source [, count])

Returns a new String value who contains the specified String characters repeated count times.

Parameters:

Name	Type	Argument	Default	Description
`source`	string			The string reference to repeat.
`count`	number	<optional>	1	The number of time to repeat the passed-in expression.

Returns:

A new expression who contains the specified String characters repeated count times.

Example

trace( repeat( "hello" ) ) ; // hello
trace( repeat( "hello" , 0 ) ) ; // ""
trace( repeat( "hello" , 1 ) ) ; // hello
trace( repeat( "hello" , 2 ) ) ; // hellohello
trace( repeat( "hello" , 3 ) ) ; // hellohellohello

trace( repeat( "hello" , -1 ) ) ; // throws RangeError =>'repeat count must be non-negative'
trace( repeat( "hello" , Infinity ) ) ; // throws RangeError =>'repeat count must be less than infinity'

startsWith(source, value)

Checks if this string starts with the specified prefix.

Parameters:

Name	Type	Description
`source`	string	The string reference to evaluates.
`value`	string	The string expression to find in first in the source.

Returns:

true if the value is find in first.

Example

trace( startsWith( "hello.txt" , "hello" ) ) ; // true

trim(source [, chars])

Removes all occurrences of a set of specified characters (or strings) from the beginning and end of this instance.

Parameters:

Name	Type	Argument	Default	Description
`source`	string			The string reference to trim.
`chars`	array	<optional>	null	The optional Array of characters to trim. If this argument is null the `core.chars.whiteSpaces` array is used.

Returns:

The new trimed string.

Example

trace( trim("\r\t   hello world   \t ") ); // hello world
trace( trim("-_hello world_-",["-","_"]) ) ; // hello world

trimEnd(source [, chars])

Removes all occurrences of a set of characters specified in an array from the end of this instance.

Parameters:

Name	Type	Argument	Default	Description
`source`	string			The string reference to trim.
`chars`	array	<optional>	null	The optional Array of characters to trim. If this argument is null the `core.chars.whiteSpaces` array is used.

Returns:

The new trimed string.

Example

trace( trimEnd("---hello world---" , ["-"] ) ) ; // ---hello world

trimStart(source [, chars])

Removes all occurrences of a set of characters specified in an array from the beginning of this instance.

Parameters:

Name	Type	Argument	Default	Description
`source`	string			The string reference to trim.
`chars`	array	<optional>	null	The optional Array of characters to trim. If this argument is null the `core.chars.whiteSpaces` array is used.

Returns:

The new trimed string.

Example

trace( trimStart( "---hello world---" , ["-"] ) ); // hello world---

truncate(source, length, prune)

Truncates a string expression, accounting for word placement and character count.

Parameters:

Name	Type	Description
`source`	string	The string reference to transform.
`length`	number	The number of character to keep.
`prune`	string	The string suffix to finalize the truncated expression.

Returns:

The new truncated string.

Example

trace( truncate("this is some long text")) ; // ...
trace( truncate("this is some long text",3) ) ; // ...
trace( truncate("this is some long text",7) ) ; // this is...
trace( truncate("this is some long text",12) ) ; // this is some...
trace( truncate("this is some long text",12," etc.") ) ; // this is some, etc.

ucFirst(source)

Capitalize the first letter of a string.

Parameters:

Name	Type	Description
`source`	string	The string reference to transform.

Returns:

The capitalized first expression.

Example

trace( ucFirst("hello world")) ; // Hello world

ucWords(source [, separator])

Capitalize each word in a string.

Parameters:

Name	Type	Argument	Default	Description
`source`	string			The string reference to transform.
`separator`	string	<optional>	' '	The optional separator expression.

Returns:

The new string expression with each word capitalized.

Example

trace( ucWords("hello world")) ; // Hello World
trace( ucWords("hello-world","-")) ; // Hello-World

validateUUID(uuid, vers)

Determines whether the uuid is valid, converting it from a buffer if necessary.

Parameters:

Name	Type	Description
`uuid`	String	The uuid expression to validate.
`vers`	Number	The optional version of the uuid to validate.

Returns:

true if the uuid expression is valid.

Type: Boolean

Example

trace( validateUUID("c01bfdc3-405c-45a1-9dec-06e6e830bee1") ) ; // true

versionUUID(uuid)

Extracts the version from the UUID, which is (by definition) the M in xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

Parameters:

Name	Type	Description
`uuid`	String	The uuid expression

Returns:

The version number of the uuid expression.

Type: Number

Example

trace( versionUUID("c01bfdc3-405c-45a1-9dec-06e6e830bee1") ) ; // 4