@yr/keys

Utility for working with segmented strings of type foo/bar.

Usage

var keys = require('@yr/keys');

keys.slice('foo/bar', 0, 1); //=> 'foo'
keys.last('foo/bar'); //=> 'bar'
keys.length('/foo/bar/boo'); //=> 3
keys.join('foo', 'bar/boo'); //=> 'foo/bar/boo'

API

separator: character used to separate key segments (default is "/").

slice(key, begin, [end]): retrieve segments of key based on slice indexes begin and (optionally) end.

keys.slice('foo/bar', 0); //=> 'foo/bar'
keys.slice('foo/bar', 0, 1); //=> 'foo'
keys.slice('foo/bar', -1); //=> 'bar'

first(key): retrieve first segment of 'key'.

keys.first('foo'); //=> 'foo'
keys.first('foo/bar'); //=> 'foo'
keys.first('/foo/bar'); //=> 'foo'

last(key): retrieve last segment of 'key'.

keys.last('foo'); //=> 'foo'
keys.last('foo/bar'); //=> 'bar'
keys.last('/foo/bar'); //=> 'bar'

length(key): retrieve number of segments for 'key'.

keys.length('foo'); //=> 1
keys.length('foo/bar'); //=> 2
keys.length('/foo/bar'); //=> 2

join(...keys): join ...keys with separator.

keys.join('foo', 'bar'); //=> 'foo/bar'
keys.join('foo', 'bar', 0); //=> 'foo/bar/0'
keys.join('foo', null, 'bar'); //=> 'foo/bar'

merge(...keys): merge ...keys with separator, taking care of overlaps.

keys.merge('foo', 'bar'); //=> 'foo/bar'
keys.merge('foo/bar', 'bar/boo'); //=> 'foo/bar/boo'
keys.merge('/foo/bar', '/foo/bar/boo'); //=> '/foo/bar/boo'
keys.merge('foo/bar/boo', 'bar/boo', 'boo/bang'); //=> 'foo/bar/boo/bang'

escape(key): escape key segment separators.

keys.escape('foo/bar'); //=> 'foo___bar'

unescape(key): unescape key segment separators.

keys.unescape('foo___bar'); //=> 'foo/bar'