Allows manipulation and formatting of text strings and determination and location of substrings within strings.
Size of the cache, dictating how many values can be cached at a given time.
Configured options. Combination of global-options GlobalUnitConfig and the options passed on instantiation.
On-demand observable events.
An Observable to observe future values, unlike the default Observable it doesn't replay when subscribed to, rather it waits for the next value.
Length of the string value.
Index of the current value in the UnitBase.cachedValues
Count of all the cached values.
A counter to keep track of how many times has a Unit, System, Action or Cluster emitted.
Number of times a Unit, System, Action or Cluster has emitted.
Indicates whether the value is undefined or not.
It should be preferred if the Unit is configured to be immutable, as it doesn't create a copy.
Indicates whether the Unit is frozen or not. See freeze for more details.
Note: It's not the same as Object.isFrozen.
Indicates whether the Unit is muted or not. See mute for more details.
All the cached values. Creates a copy if the Unit is configured to be immutable.
The initialValue provided on instantiation. Creates a copy if the Unit is configured to be immutable.
If the Unit has a non-primitive value, use it to get access to the current value, without creating a deep-copy.
This can come in handy if the Unit is configured to be immutable, and you want to perform a non-mutating action without creating a deep-copy of the value.
Current value of the Unit.
Go back in the cache and re-emit the previous value from the cache,
without creating a new entry in the cache.
It can be used as Undo.
It doesn't work if the Unit is frozen isFrozen.
It only works if there's a previously dispatched value in the cache.
ie: the cacheIndex is not 0
true if the cache-navigation was successful, otherwise false.
After going back in the cache (ie: re-emitting an old value from the cache),
use this method to go to the next value, without creating a new entry in the cache.
It can be used as Redo.
It doesn't work if the Unit is frozen isFrozen.
It only works if the current value is not the last value in the cache.
ie: the cacheIndex is not equal to cachedValuesCount - 1
true if the cache-navigation was successful, otherwise false
Use this method to re-emit a value from the cache, by jumping specific steps backwards or forwards,
without creating a new entry in the cache.
It doesn't work if the Unit is frozen isFrozen or steps is not a number.
It only works if the new calculated index is in the bounds of cachedValues,
ie: the new-index is >= 0, and less than cachedValuesCount, but
not equal to current cacheIndex.
Number of steps to jump in the cache, negative to jump backwards, positive to jump forwards
true if the cache-navigation was successful, otherwise false.
After going back in the cache (ie: re-emitting an old value from the cache),
use this method to re-dispatch the last (latest) value in the cache,
without creating a new entry in the cache.
It doesn't work if the Unit is frozen isFrozen. It only works if the cacheIndex is not already at the last value in the cache.
true if the cache-navigation was successful, otherwise false
Use this method to re-emit the first value in the cache,
without creating a new entry in the cache.
It doesn't work if the Unit is frozen isFrozen.
It only works if the cacheIndex is not already at the last value in the cache.
ie: the cacheIndex is not 0.
true if the cache-navigation was successful, otherwise false
Creates a new Observable using the default Observable as source. Use this to conceal other aspects of a Unit, System, Action or Cluster except the Observable part.
An Observable with the value of a Unit, System, Action or Cluster.
A helper method that creates a stream by subscribing to the Observable returned by the param observableProducer callback.
Ideally the callback function creates an Observable by applying Observable.pipe.
Just know that you should catch the error in a sub-pipe (ie: do not let it propagate to the main-pipe), otherwise as usual the stream will stop working, and will not react on any further emissions.
A callback function that should return an Observable.
To manually re-emit the last emitted value again.
It doesn't work if the Unit is frozen isFrozen or muted isMuted.
Note: Even if the Unit is immutable, it does not create a copy of the Unit's value, it merely re-emits the last emitted value.
true if replayed successfully, otherwise false.
Converts the value to JSON string, using JSON.stringify.
Method to dispatch new value by passing the value directly, or
by passing a value-producer-function that produces the value using the current value.
Given a value, it either gets dispatched if it's allowed by wouldDispatch,
or it gets ignored if not allowed.
If the Unit is not configured to be immutable, then
the value-producer-function (param valueOrProducer) should not mutate the current value,
which is provided as an argument to the function.
If you mutate the value, then the cached-value might also get mutated,
as the cached-value is saved by reference, which can result in unpredictable state.
Dispatch options.
true if value got dispatched, otherwise false.
If UnitConfig.dispatchDebounce is enabled, then it'll return undefined.
Method to dispatch new value by passing the value directly, or
by passing a value-producer-function that produces the value using the current value.
Given a value, it either gets dispatched if it's allowed by wouldDispatch,
or it gets ignored if not allowed.
If the Unit is not configured to be immutable, then
the value-producer-function (param valueOrProducer) should not mutate the current value,
which is provided as an argument to the function.
If you mutate the value, then the cached-value might also get mutated,
as the cached-value is saved by reference, which can result in unpredictable state.
true if value got dispatched, otherwise false.
If UnitConfig.dispatchDebounce is enabled, then it'll return undefined.
Holistically clears the Unit,
unfreezes using unfreeze,
clears the value using clearValue,
completely clears cache using clearCache,
in that specific order.
Clear cache options for clearCache.
Clears the cached values, current value stays intact, but it gets removed from the cache.
Meaning, if you dispatch a new value you can't goBack.
To keep the last value in the cache, pass {leaveLast: true} in the param options.
It only works if the Unit is not frozen and there's something left to clear after evaluating the param options.
Similar to preserving the last value, you can preserve the first value by passing {leaveFirst: true}.
Or preserve both first and last value by passing both options together.
Clear cache options
true if the cache was cleared, otherwise false
Clears persisted value from persistent storage.
It doesn't turn off persistence, future values will get persisted again.
It only works if the Unit is configured to be persistent. ie: options.persistent is true.
true if the Unit is configured to be persistent, otherwise false.
true if the value was cleared, otherwise false
Temporarily disables most of the functions of the Unit, except unfreeze,
mute/unmute, clear and reset.
It's not the same as Object.freeze.
Freezing prevents any new values from getting dispatched,
it disables all the mutating functions.
Which eventually ensures that no event is emitted while the Unit is frozen,
however all the read operations and operations that do not emit a value are allowed.
Get cached value at a given index.
The index of cached value
The cached value if it exists, otherwise undefined
Mute the Unit, to stop emitting values as well as events, so that the subscribers are not triggered.
All other functionalities stay unaffected. ie: cache it still updated, value is still updated.
Note: If you subscribe to the default Observable while the Unit is muted,
it will replay the last value emitted before muting the Unit,
because new values are not being emitted.
Holistically resets the Unit,
unfreezes using unfreeze,
resets the value using resetValue,
clears cache using clearCache and by default leaves last value;
in that specific order.
Clear cache options for clearCache. default is {leaveLast: true}
Resets the value by dispatching the initial-value, UnitConfig.initialValue if provided,
otherwise dispatches the default value.
It only works if the Unit is not frozen,
and the value is not equal to the initialValue.
true if the reset was successful, otherwise false
Unfreezes the Unit, and re-enables all the functions disabled by freeze.
It only works if the Unit is frozen.
Unmute the Unit, to resume emitting values, and events.
If a value was dispatched while the Unit was muted, the most recent value immediately gets emitted,
so that subscribers can be in sync again.
However, other events$ are lost, and they will only emit on the next event.
It only works if the Unit is muted.
Moreover, it works even if the Unit is frozen,
but no value will be emitted because no values would have been dispatched while the Unit was frozen.
Extends UnitBase.wouldDispatch and adds additional check for type string, which cannot be bypassed even by using {@link force}.
The value to be dispatched.
Whether dispatch-checks should be bypassed or not.
A boolean indicating whether the param value would pass the dispatch-checks if dispatched.
Iterator
Returns an <a> HTML anchor element and sets the name attribute to the text value
Returns a <big> HTML element
Returns a <blink> HTML element
Returns a <b> HTML element
Returns the character at the specified index.
The zero-based index of the desired character.
Returns the Unicode value of the character at the specified location.
The zero-based index of the desired character. If there is no character at the specified index, NaN is returned.
Returns a nonnegative integer Number less than 1114112 (0x110000) that is the code point value of the UTF-16 encoded code point starting at the string element at position pos in the String resulting from converting this object to a String. If there is no element at that position, the result is undefined. If a valid UTF-16 surrogate pair does not begin at pos, the result is the code unit at pos.
Returns a string that contains the concatenation of two or more strings.
The strings to append to the end of the string.
Returns true if the sequence of elements of searchString converted to a String is the same as the corresponding elements of this object (converted to a String) starting at endPosition – length(this). Otherwise returns false.
Returns a <tt> HTML element
Returns a <font> HTML element and sets the color attribute value
Returns a <font> HTML element and sets the size attribute value
Returns a <font> HTML element and sets the size attribute value
Returns true if searchString appears as a substring of the result of converting this object to a String, at one or more positions that are greater than or equal to position; otherwise, returns false.
search string
If position is undefined, 0 is assumed, so as to search all of the String.
Returns the position of the first occurrence of a substring.
The substring to search for in the string
The index at which to begin searching the String object. If omitted, search starts at the beginning of the string.
Returns an <i> HTML element
Returns the last occurrence of a substring in the string.
The substring to search for.
The index at which to begin searching. If omitted, the search begins at the end of the string.
Returns an <a> HTML element and sets the href attribute value
Determines whether two strings are equivalent in the current locale.
String to compare to target string
Matches a string with a regular expression, and returns an array containing the results of that search.
A variable name or string literal containing the regular expression pattern and flags.
Returns the String value result of normalizing the string into the normalization form named by form as specified in Unicode Standard Annex #15, Unicode Normalization Forms.
Applicable values: "NFC", "NFD", "NFKC", or "NFKD", If not specified default is "NFC"
Returns the String value result of normalizing the string into the normalization form named by form as specified in Unicode Standard Annex #15, Unicode Normalization Forms.
Applicable values: "NFC", "NFD", "NFKC", or "NFKD", If not specified default is "NFC"
Pads the current string with a given string (possibly repeated) so that the resulting string reaches a given length. The padding is applied from the end (right) of the current string.
The length of the resulting string once the current string has been padded. If this parameter is smaller than the current string's length, the current string will be returned as it is.
The string to pad the current string with. If this string is too long, it will be truncated and the left-most part will be applied. The default value for this parameter is " " (U+0020).
Pads the current string with a given string (possibly repeated) so that the resulting string reaches a given length. The padding is applied from the start (left) of the current string.
The length of the resulting string once the current string has been padded. If this parameter is smaller than the current string's length, the current string will be returned as it is.
The string to pad the current string with. If this string is too long, it will be truncated and the left-most part will be applied. The default value for this parameter is " " (U+0020).
Returns a String value that is made from count copies appended together. If count is 0, the empty string is returned.
number of copies to append
Replaces text in a string, using a regular expression or search string.
A string to search for.
A string containing the text to replace for every successful match of searchValue in this string.
Replaces text in a string, using a regular expression or search string.
A string to search for.
A function that returns the replacement text.
Finds the first substring match in a regular expression search.
The regular expression pattern and applicable flags.
Returns a section of a string.
The index to the beginning of the specified portion of stringObj.
The index to the end of the specified portion of stringObj. The substring includes the characters up to, but not including, the character indicated by end. If this value is not specified, the substring continues to the end of stringObj.
Returns a <small> HTML element
Split a string into substrings using the specified separator and return them as an array.
A string that identifies character or characters to use in separating the string. If omitted, a single-element array containing the entire string is returned.
A value used to limit the number of elements returned in the array.
Returns true if the sequence of elements of searchString converted to a String is the same as the corresponding elements of this object (converted to a String) starting at position. Otherwise returns false.
Returns a <strike> HTML element
Returns a <sub> HTML element
Gets a substring beginning at the specified location and having the specified length.
The starting position of the desired substring. The index of the first character in the string is zero.
The number of characters to include in the returned substring.
Returns the substring at the specified location within a String object.
The zero-based index number indicating the beginning of the substring.
Zero-based index number indicating the end of the substring. The substring includes the characters up to, but not including, the character indicated by end. If end is omitted, the characters from start through the end of the original string are returned.
Returns a <sup> HTML element
Converts all alphabetic characters to lowercase, taking into account the host environment's current locale.
Returns a string where all alphabetic characters have been converted to uppercase, taking into account the host environment's current locale.
Converts all the alphabetic characters in a string to lowercase.
Returns a string representation of a string.
Converts all the alphabetic characters in a string to uppercase.
Removes the leading and trailing white space and line terminator characters from a string.
Removes the trailing white space and line terminator characters from a string.
Removes the leading white space and line terminator characters from a string.
Removes the trailing white space and line terminator characters from a string.
Removes the leading white space and line terminator characters from a string.
Returns the primitive value of the specified object.
StringUnit is a reactive storage Unit that emulates
string.It only accepts
stringdata type as its value. It ensures that at any point of time the value would always bestring.StringUnit implements all the
String.prototypemethods that are available in the environment/browser its running, including polyfills. e.g.:trim,match,includes, etc.Learn more about Units here.
Learn more about StringUnit here.
Just like every other ActiveJS Unit:
Observable