String

Description

Extends String object.

Public Member Functions
string	arg (value)
string	elideLeft (int maxLen)
string	elideMiddle (int maxLen)
string	elideRight (int maxLen)
string	format (format, args)
string	simplified ()
string	appendLine (string line, int maxLines, separator='\n')
string	getLines (int maxLines, int fromLine=0, string separator='\n')

Static Public Member Functions
string	elideLeft (any str, int maxLen)
string	elideMiddle (any str, int maxLen)
string	elideRight (any str, int maxLen)
string	appendLine (string text, string line, int maxLines, string separator='\n')
string	getLines (string text, int maxLines, int fromLine=0, string separator='\n')

Member Function Documentation

arg()

string arg

(

value

)

Returns a copy of this string with the lowest numbered place marker replaced by value.

Place markers begin with a % symbol followed by a number in the 1 through 99 range, i.e. %1, %2, ..., %99.

The following example prints "There are 20 items":

var message = "There are %1 items"
var count = 20
console.log(message.arg(count))

See also

String.format(), sprintf()

elideLeft() [1/2]

string elideLeft

(

int

maxLen

)

Left-trims this string to maxLen characters and adds an ellipsis character (…) at the start if the input string was shortened.

Returns a new string.

See also

elideMiddle(), elideRight()

elideMiddle() [1/2]

string elideMiddle

(

int

maxLen

)

Removes characters from the middle of this string so that the total remaining length doesn't exceed maxLen characters, and adds an ellipsis character (…) in the middle if the input string was shortened.

Returns a new string.

If maxLen is an odd number, the extra character is placed before the ellipsis.

See also

elideLeft(), elideRight()

elideRight() [1/2]

string elideRight

(

int

maxLen

)

Right-trims this string to maxLen characters and adds an ellipsis character (…) to the end if the input string was shortened.

Returns a new string.

See also

elideLeft(), elideMiddle()

elideLeft() [2/2]

string elideLeft ( any  str, int  maxLen  )

static

Left-trims str to maxLen characters and adds an ellipsis character (…) at the start if the input string was shortened.

Returns a new string.

This static version will coerce the input str into a string type if it isn't one already.

See also

elideMiddle(), elideRight()

elideMiddle() [2/2]

string elideMiddle ( any  str, int  maxLen  )

static

Removes characters from the middle of the string str so that the total remaining length doesn't exceed maxLen characters, and adds an ellipsis character (…) in the middle if the input string was shortened.

Returns a new string.

If maxLen is an odd number, the extra character is placed before the ellipsis.

This static version will coerce the input str into a string type if it isn't one already.

See also

elideLeft(), elideRight()

elideRight() [2/2]

string elideRight ( any  str, int  maxLen  )

static

Right-trims str to maxLen characters and adds an ellipsis character (…) to the end if the input string was shortened.

Returns a new string.

This static version will coerce the input str into a string type if it isn't one already.

See also

elideLeft(), elideMiddle()

format()

string format	(	format	,
		args
	)

Formats format string using the provided arguments in args, if any, using .NET-style formatting syntax.

Parameters

format	The formatting string used to format the additional arguments.
args	Zero or more arguments for the format string.

Formatting is done using format strings almost completely compatible with the String.Format method in Microsoft .NET Framework.

For example:

String.format(
    "Welcome back, {0}! Last seen {1:M}",
    "John Doe", new Date(1985, 3, 7, 12, 33)
);
// output: "Welcome back, John Doe! Last seen April 07"

There is also a convenience global function available as an alias, named simply Format(). It works identically to String.format() but is shorter to type.

See formatting string reference at
https://learn.microsoft.com/en-us/dotnet/standard/base-types/formatting-types

This extension is originally from the String.format for JavaScript project. There are some examples and references available at that site. The original sffjs object referenced in their documentation is available in this script engine as Sffjs.

See also

Number.format(), Date.format(), and sprintf() for "printf-style" string formatting.

simplified()

string simplified

(

)

Returns this string with leading, trailing, and all redundant internal whitespace removed.

contents of this byte array as a Base64-encoded string. Example:

var str = "  lots\t of\nwhitespace\r\n ";
str = str.simplified();
// str == "lots of whitespace";

appendLine() [1/2]

string appendLine	(	string	line,
		int	maxLines,
		separator	= '\n'
	)

Appends string line to current string, and returns a new block with up to maxLines lines.

If maxLines is zero or negative, returns the full resulting string. The newline (\n) is used as separator by default, or a custom separator string can be specified in separator argument.

appendLine() [2/2]

string appendLine ( string  text, string  line, int  maxLines, string  separator = '\n'  )

static

Appends string line to text and returns a new block with up to maxLines lines.

Static version of String.prototype.appendLine(), above. Used, for example, like this: String.appendLine("Original string", "New line to append", 4)

getLines() [1/2]

string getLines	(	int	maxLines,
		int	fromLine = 0,
		string	separator = '\n'
	)

Splits string text into lines based on separator and returns maxLines of text starting at fromLine (zero-based index).

Default maxLines is 1, fromLine is zero (the start) and default separator is "\n". Specify a negative fromLine to count lines from the end instead of the beginning (so -1 returns one line from the end). The result may be the complete input if there were fewer then maxLines found in it.

getLines() [2/2]

string getLines ( string  text, int  maxLines, int  fromLine = 0, string  separator = '\n'  )

static

Splits string text into lines based on separator and returns maxLines of text starting at fromLine (zero-based index).

Static version of String.prototype.getLines(), above. Used, for example, like this: String.getLines("Text\nWith some\nLines\n", 1, -1)