esstringbuilderplus v1.1.5
ECMAScript String Builder PLUS
es-stringbuilder-plus
delivers a way to build a string (actually
a wrapped String
instance delivering a mutable string value).
Instances can use native String methods and a number of custom methods to change their internal value without the need for re-assigning.
ECMAScript (ES) string builder PLUS is programmed in a class free object oriented way.
Also on NPM
All custom instance getters and methods
Notes
- The code follows ES20XX, so will work with all up to date modern browsers and/or within later nodejs versions.
- All (not deprecated)
native String methods
(e.g.
toUpperCase
) are converted and usable in the same way you would use them for a regular string. - A string builder instance can be created using the imported 'constructor' (let's call it
$SB
).$SB
can be called either as a regular function (e.g.$SB("some string")
) or as a tagged template (e.g$SB`some string`
). It can only receive a String or a Number. Any other parameter type will result in an instance with an empty string as its value. - ES String Builder PLUS is a lightweight stand alone module. We also have the more comprehensive es-string-fiddler module available. That module delivers more functionality, e.g. methods to sanitize HTML strings, create Regular Expressions from multiline strings and extend the constructor with ones own custom methods.
- In the following the custom getters and methods of an instance are described.
- With 'value' the current value of a string builder instance is meant.
- Value changing (mutating) getters and methods of an instance and the results of native String method calls are 'chainable'.
- Chainable means the result can be followed by a new getter-/method-call (e.g.
[instance].toUpperCase().quot("[,]")
).
- The constructor enables creating user defined extensions, using
[constructor].addExtension
.- syntax:
[constructor]..addExtension(name: string, function(me: instance, [...arguments]) {...}): function)
when...arguments
is empty, the extension will be a getter. Otherwise it will be a method. The first parameter is the instance to apply the extension function to. It is obligatory and must always be the first argument of the extension function. The return value of the extension function may be a string or the (modified) instance. The user defined extension method for an instance returns itself. Thus it is is always chainable. - example 1 (
$SB
is the constructor):$SB.addExtension(`sayOk`, me => me.prepend(`*OK* `));
sayOk
is now a getterconst test = $SB`test123`.sayOk
=>test.value
: "OK test123" - example 2:
$SB.addExtension(`replaceFirstWord`, (me, replacement) =>
(me.indexOf(" ") ? replacement : "" ) + me.value.slice(me.indexOf(` `));
const test = $SB`test123 4567`.replaceFirstWord(`123`)
=>test.value
=> "123 456"
const test = $SB`test1234567`.replaceFirstWord(`123`)
=>test.value
=> "test123456"
- syntax:
append(str2Append)
mutates, chainable Appendsstr2Append
to the value.as(newValue)
mutates, chainable alias for[instance].is
.clear
getter, mutates, chainable Clears the value - effectively rendering it to an empty string.clone
getter, chainable Creates a clone of the instance.cloneWith(value: string or template string)
chainable Creates a clone of the instance. Either re-assign to a new value, or use as intermediate value.empty
getter, mutates, chainable Alias ofclear
. Clears the value, effectively rendering it to an empty string.firstUp
getter, mutates, chainable Convert the first letter of the value to uppercase.indexOf(stringToFindIndexOf: string|RegExp, [startPosition]: int)
native (override), returns a value (not mutating)
Returns the (zero based) index of the substring to find (optional starting at[startPosition]
)
orundefined
(instead of -1) when nothing was found. Furthermore[stringToFindIndexOf]
may be a regular expression.initial
getter, returns a value (not mutating) Retrieves the value the instance was instantiated with (see alsoreset
).interpolate(...replacementTokens)
mutates, chainable Interpolates terms from the value with one or more replacement objects ([replacementTokens]
). see the GitHub StringInterpolator library or the demo for how to use.is(newValue: string/template string))
mutates, chainable Assigns[newValue]
to the value.Notes:
[instance].is(...)
will not change the initial instance value (which is stored for use in[instance].reset
).- to re-assign the instance value one can also use the setter
[instance].value = ...
lastIndexOf(stringToFindIndexOf: string|RegExp, [beforePosition]: int)
native (override), returns a value (not mutating)
Returns the (zero based) index of the substring to find (optional before[beforePosition]
in the string)
orundefined
(instead of -1) when nothing was found. Furthermore[stringToFindIndexOf]
may be a regular expression.prepend(str2Prepend: string/template string)
mutates, chainable inserts[str2Prepend]
before the value.quot(quotes = '"')
mutates, chainable Adds[quotes]
to the start and end of the value.[quotes]
can be one character, or a string of two comma separated characters/string (e.g."[,]"
or"*start*,*end*"
).quot4Print(quotes = '"')
returns a value (not mutating) Equal toquot
, but will not change the value.
This will return the value surrounded with the given[quotes]
, e.g. for printing to screen.remove(start: number, end: number)
mutates, chainable Removes the part of the value from[start]
to[end]
. If neither[start]
and/or[end]
are given, nothing will happen to the value. If one of[start]
or[end]
is not given, the defaults are respectively 0 or the length of the value.[end]
can be negative (meaning[end]
characters from the end of the value).reset
getter, mutates, chainable Sets the value back to the value the instance was instantiated with.surroundWith({r: string (default ""), [r: string (default "")]})
mutates, chainable
Surround the value with strings from[l]
(eft) and[r]
(ight).reverse
getter, mutates, chainable Reverses the value (e.g.hello
=>olleh
). Including strings containing Unicode 'surrogate pairs'toCamel
getter, mutates, chainable converts a value with patternaaa-bbb
to camelCased notation (aaaBbb
).toDashed
getter, mutates, chainable converts a value with patternaaaBbbCcc
to dashed notation (aaa-bbb-ccc
)toLower
getter, mutates, chainable alias forString.prototype.toLowerCase
.toUpper
getter, mutates, chainable alias forString.prototype.toUpperCase
.truncate(at:number, { html = false, wordBoundary = false } = {} )
mutates, chainable Truncates the value from its start to[at]
and adds either...
([html]
false) or&hellip
([html]
true) to it. When[wordBoundary]
is true, truncates at the last word within the truncated result.value
getter, setter (mutates) Retrieves the actual instance value or sets it.wordsUp
getter, mutates, chainable converts all first letters of words within the value to uppercase