README
varsize-string
Varsize-string is a JavaScript CommonJS (node.js) package for working with strings where the different characters have different sizes.
Installation & Usage
With npm you can install and use the varsize-string
like this:
$ npm install varsize-string --save
With the package being successfully installed you can create an instance like this:
function charWidth(charCode, formerCharCode, inString, pos) {
/* in this example a-z (lower-case) is 0.8 the width of other characters */
return (charCode >= 97 && charCode <= 122 ) ? 0.8 : 1
}
var VarSizeString = require('varsize-string')
var str = new VarSizeString('ABCdef', charWidth)
var str2 = VarSizeString('abcDEF', charWidth) // You don't need to use `new`
Application
The most important application of varsize-string
is in combination with
wcsize
that identifies the size of strings rendered in a common terminal,
see wcstring
for a shorthand combination of both.
It can also be used in a (visual) web context to correctly wrap
or truncate
strings.
Operations
On the instance you can apply a set of operations. Note that the following explanation uses size
as an accumulated amount of width and width
as a single-line size
.
.width()
Get the size
of the widest line in the string.
.size()
Get the size
of the complete string.
.sizeBeforeFirst(search, [<int> startOffset])
Analogous to String.indexOf
. Looks for the first occurance of search
. Optionally takes startOffset
which is the size
of characters that have to happen before the search takes place (default=0).
.sizeBeforeLast(search, [<int> endOffset])
Analogous to String.lastIndexOf
. Looks for the last occurance of search
.
Optionally takes endOffset
which is the size offset from the end of the string from which to search for search
.
.substring(<int> startSize, [<int> endSize])
Analogous to String.substring
. This method will return the fully visible characters between startSize
and endSize
. If endSize
is not given it will assume a substring from startSize
until the end of the string.
However: Unlike String.substring
, this method returns an object with the properties size
and string
in order to know the size of the substring.
Example:
var vsstring = require('varsize-string')
vsstring('abcdef', charWidth).substring(0, 3) // {string: 'abc', size: 2.4}
.substr(<int> startSize, [<int> size])
Equal to .substring(startSize, startSize + size)
.
.truncate(<int> size, <varsize-string || String> suffix)
Truncates the string after a size. Will append the given suffix
to the string if it does exceed the size.
.pop()
Removes the last character from the string and returns the new .size()
.
.wrap(<int> width, [padding])
Normalizes the string in order for all lines to fit within width
.
Example:
var vsstring = require('varsize-string')
vsstring('abcdef', charWidth).wrap(3) // 'abc\ndef'
vsstring('ab cd ef', charWidth).wrap(5) // 'ab cd\nef'
vsstring('ab cd ef', charWidth).wrap(3) // 'ab\ncd\nef'
Padding
The padding option takes a padding specification and applies it to the wrapping process.
Example:
var padding = {
first: {left: ' - ', right: ' '},
regular: {left: ' ', right: ' '}
}
vsstring('abcdefghijklmnop', charWidth).wrap(10, padding)
// - abcdef
// ghijkl
// mnop
There are a few shorthands to specifying the padding:
padding = ' '
... is equals to ...
{
first: ' ',
regular: ' '
}
... is equals to ...
{
first: {left: ' ': right: undefined},
regular: {left: ' ': right: undefined}
}
Also you can preset left/right for both first and regular:
{
right: 'x',
first: {left: ' - '},
regular: {left: ' '}
}
... is equal to ...
{
first: {left: ' - ', right: 'x'},
regular: {left: ' ', right: 'x'}
}
Note that the left/right presets override the first/regular specification:
{
left: 'x',
first: '-',
regular: ' '
}
... is equal to ...
{
first: {left: 'x', right: undefined},
regular: {left: 'x', right: undefined}
}
Also it supports a fallback to regular if first is missing:
{
regular: {left: 'x', right: undefined}
}
... is equal to ...
{
first: {left: 'x', right: undefined},
regular: {left: 'x', right: undefined}
}
vsstring.padding(characterLookup, [process], [width], padding)
Turns a flexible padding definition into a clear padding definition. You can pass in an optional process
variable to process the strings before they are being turned into varsizes-strings. You can also pass-in a width
to make sure that the padding will not exceed the width of, say, a wrapped string.