Namespace: strings

core. strings

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

Author:
License:

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