need-some-basic.js





_need-some_ is a collection of small yet useful functions.
The basic package provides core functionality that can be used in many javascript and typescript applications.
Installation
Simply install as dependency
npm install @need-some/basic --save
stdmethods
Methods for compatibility, but not defined as polyfill
$3
Adjust number, so it fits into the given borders. If the given number is lower than the lower bound (or greater than the upper bound), the bound is returned.
If a bound is undefined, this side is not adjusted. If the lower bound is greater than the upper bound, the result is kind of unexpected, and always one of the bounds.
adjust (n: number, lower: number|undefined, upper: number|undefined): number
$3
Truncate fractional part of number. Returns the signed integer part
trunc (n: number): number
$3
Pad a string to have at least n characters. The c characters are appended in front (left) of the string
padLeft (s: string, c: string, n: number): string
$3
Pad a string to have at least n characters. The c characters are appended at the end (right) of the string
padRight (s: string, c: string, n: number): string
$3
Pad a number with leading zeros to have at least n characters.
If the number is negative, the numbers absolute value is padded to one character less and a leading minus sign is added.
If the number string is already longer than the given length, it is returned without change.
padNumber (s: number, n: number): string
$3
Check whether a string starts with another string.
startsWith (str: string, start: string): boolean
$3
Check whether a string ends with another string
endsWith (str: string, start: string): boolean
$3
Split string on delimiter. A delimiter can be delimited by backslash '\'
splitSimple (s: string, delim: string): string[]
$3
Split well-formed string into parts with brakets.
Within the enclosed strings, the brakets will not be considered.
* E.g.
'a+(b+(c+d))+(e+f)' will be split into
'a+',
'b+(c+d))',
'+',
'(e+f)'The resulting array will always start with an unenclosed part and have one unenclosed part between the enclosed ones.
These parts may be empty strings to provide a strict structure
* E.g. '(b+(c+d))' will be split into '', 'b+(c+d))'
* and '(b+(c+d))(e+f)' will be split into '', 'b+(c+d))', '', 'e+f'
Alternative start delimiters can be used to mask end delimiter within the enclosed parts
* E.g. 'a${b:{c}}' with start '${' and end '}' needs alternative start '{' so the outmost closing bracket is found
splitBracket(s: string, dstart: string, dend: string, altdstarts?: string[]): string[]
$3
Return the nested child of an object.
lookup(object: any, key: (string | number) | ((string | number)[])): any
$3
Set the value of a nested child of an object.
overwrite(object: any, key: (string | number) | ((string | number)[]), value: any): void
Converters
Interfaces for converters of string (or similar serialized form) to an object and vice versa are defined here.
The main interfaces are
Marshaller to serialize objects with its method marshal(object: T): S and Unmarshaller to deserialize with unmarshal(serialized: S): T
S is the type of the serialization (e.g. string) and T is the deserialized object type.
There are some convenience methods to use converters
$3
Create an instance to marshal with the given function
marshal(fun: (object: T) => S): Marshaller
$3
Create an instance to unmarshal with the given function
unmarshal(fun: (serialized: S) => T): Unmarshaller
$3
Create an instance to marshal with the given function
convert(marshalFunction: (object: T) => S, unmarshalFunction: (serialized: S) => T): Converter
$3
Construct a new converter instance that simple returns the given instance
identity(): Converter {
$3
Construct a new converter instance that calls the given converter for each array item.
map(converter: Converter): Converter
$3
Construct a new string converter instance which allows null. If null is unmarshalled, an empty string is returned.
nullsafestring(converter: Converter): Converter
$3
Construct a new converter instance which allows null.
nullsafe(converter: Converter): Converter
$3
Construct a new converter instance which allows undefined.
undefinedsafe(converter: Converter): Converter
Types
$3
Color is a class that parses and holds the color values.
$3
Convenience converter to convert between a color object and a hex string.