words.js
words.js is all about finding/manipulating/sorting/adding/removing words in or from a string.
words.js extends strings.js. Most methods overload strings.js methods, only to focus on words rather than characters.
Where in strings.js you use shuffle to randomly reorder the characters in a string, in words.js the overloaded
shuffle function randomly reorders the words in a string, or you can shuffle the characters of a specific word in
a string, and much more. See the API for some sweet examples.
All indexes in words.js are 1 based. Negative indexes can be used in most functions. -1 references the last
word in the internal words array, 1 references the first word.
The new Words()
object is made for chaining operations on words in strings, most of it's methods return their
own context. To return the actual value of the internal string/array, one can use .get()
or .$
or .string
.
You can use npm install words.js
when using node.js. The dependant strings.js and included types.js will
automatically be installed as well.
var Words = require('words.js');
var Types = require('words.js').Types;
var Strings = require('words.js').Strings;
var Types= Words.Types;
var Strings= Words.Strings;
types.js, strings.js and words.js are a very powerful set of building blocks that can make the life of a Javascript
developer much more pleasant and bug free IMHO.
All input and output is type save; you can throw in any type and still get a string if the expected output is of
type <string>
. If any method receives an argument of a type it cannot process, the argument will simply be ignored.
All examples are to be found in the API below.
API
Everywhere you see <string>/<number>
, it means you can either enter a String or Number argument, both will be parsed
correctly.
Words.prototype.constructor
<this> constructor( <string>/<number> string= '' )
Initializes the contextual object.
Use any combination of arguments to form a string. All invalid arguments will be ignored.
var words= new Words('numbers and strings accepted', 123, 'not objects, arrays etc..', {}, [1,2,3], 'they are simply ignored..');
console.log( words.$ );
Words.prototype.count
count
A getter to get the amount of words in the internal array.
var words= new Words('word counting included');
console.log( words.count );
Words.prototype.set
<this> set( <string>/<number> index, [index1, ..., indexN] )
Set the internal array. Use any combination of arguments to form a string. All
invalid arguments will be ignored.
var words= new Words();
words.set( 'numbers and strings accepted', 123, 'not objects, arrays etc..', {}, [1,2,3], 'they are simply ignored..' );
console.log( words.$ );
Words.prototype.get
<string> get( <string>/<number> index, [index1, ..., indexN] )
Returns the word(s) found at index(es).
var words= new Words('we can be very specific and pick any word we need');
console.log( words.get(5, -1) );
Words.prototype.$
$
A getter for .get()
var words= new Words('fetch the whole string with a getter');
console.log( words.$ );
Words.prototype.string
string
Another getter for .get(), similar to .$.
Words.prototype.xs
<this> xs( <function> callback(<string> word, <number> index) )
Access every index/word of the internal array and apply the result of callback to it. After a call to xs, the
internal array will be changed to the results of the callback.
If the callback returns true, word is applied, but you could also return word which has effectively the same result.
If the callback returns false or undefined, word will be skipped. Any character, String or Number returned by callback
will be applied to index in the internal array.
var words= new Words('words of more than 4 characters will be removed');
words.xs( function(word, index){
if( word.length < 5 )
return true;
});
console.log( words.$ );
var words= new Words('or mark words in a string');
words.xs( function(word, index){
if( word === 'mark' )
return '*marked*';
return true;
});
console.log( words.$ );
Words.prototype.find
<array> find( <string>/<number> substring )
Returns an array containing all indices(numbers) in the internal array where substring is found.
var words= new Words('finding words with words is easy!');
console.log( words.find('words') );
Words.prototype.upper
<this> upper( <string>/<number> index, <string>/<number> position )
Change words or characters in words to uppercase. If no arguments are given, all words are changed to uppercase.
If index is set to 0, all character positions denoted by position, in all words, are changed to uppercase
(if alpha of course). If indices is not set to 0, the words found on indices are changed to uppercase.
var words= new Words('you can be very specific with upper and lowercase');
console.log( words.upper(-1, -3).$ );
var words= new Words('you can be very specific with upper and lowercase');
console.log( words.upper(0, 1, -1).$ );
var words= new Words('shout it all out!');
console.log( words.upper().$ );
Words.prototype.lower
<this> lower( <string>/<number> index, <string>/<number> position )
The same as with .upper(), except for that uppercase characters are changed to lowercase.
Words.prototype.reverse
<this> reverse( <string>/<number> index, [index1, ..., indexN] )
Without arguments the internal array is reversed; not the characters, like with Strings.reverse(), but the words
positions in the internal array are reversed. If index is 0, every word is reversed, but will remain on it's original/current index,
every additional argument is then ignored. With index or indices given, the characters in the words
denoted by indices are reversed.
var words= new Words('reverse words positions');
console.log( words.reverse().$ );
var words= new Words('words are reversed in place when 0 is given');
console.log( words.reverse(0).$ );
var words= new Words('any reason to reverse a specific word?');
console.log( words.reverse(1, -1, -2).$ );
Words.prototype.shuffle
<this> shuffle( <string>/<number> index, [index1, ..., indexN] )
Shuffles the word on index, if index is given. If index is/are strings, the matching words will be shuffled.
If index is 0, every word is shuffled, but will remain on it's current index, following arguments are ignored.
Without arguments, all indices are shuffled.
var words= new Words('let\'s mess up this sentence');
console.log( words.shuffle().$ );
var words= new Words('or mess it up totally in place');
console.log( words.shuffle(0).$ );
var words= new Words('let\'s shuffle some specific words');
console.log( words.shuffle(2, -1).$ );
Words.prototype.clear
<this> clear()
Resets the internal array to empty [].
Words.prototype.remove
<this> remove( <string>/<number> indices and or words )
Removes any combination of indices or words from the internal array. Without arguments remove does nothing.
Invalid arguments are ignored
var words= new Words('removing specific words is very easy');
console.log( words.remove(2, 3, -2).$ );
Words.prototype.pop
pop( <string>/<number> amount )
Removes the last word from the internal array if no arguments are given. If amount is valid, amount words will
be removed from the internal array, starting from the last word going backwards.
var words= new Words( 'pop means: remove words from the end of this string' );
console.log( words.pop(3).$ );
Words.prototype.push
push( <string>/<number> word, [word1, ..., wordN] )
Adds words to the end of the internal array.
var words= new Words( 'push means: add to the end of this' );
console.log( words.push( 'string' ).$ );
Words.prototype.shift
shift( <string>/<number> amount )
Removes the first word from the internal array if no arguments are given. If amount is valid, amount words will
be removed from the internal array, starting from the first word going forwards.
var words= new Words( 'shift means: remove words from the start' );
console.log( words.shift(2).$ );
Words.prototype.unshift
unshift( <string>/<number> word, [word1, ..., wordN] )
Adds words to the beginning of the internal array.
var words= new Words( 'adding words to the start of a string' );
console.log( words.unshift('unshift', 'means:').$ );
Words.prototype.insert
insert( <string>/<number> index, <string>/<number> word, [word1, ..., wordN] )
Insert word(s) at index of the internal array.
var words= new Words( 'insert a word in this string' );
console.log( words.insert( 3, 'specific' ).$ );
Words.prototype.replace
replace( <string>/<number> selection, <string>/<number> replacement )
Replace all words equal to selection to replacement.
var words= new Words( 'to replace or not to replace' );
console.log( words.replace('replace', 'be').$ );
Words.prototype.sort
<this> sort()
Sorts the internal array alphabetically
var words= new Words( 'testing words is really funny actually' );
console.log( words.sort().$ );
Words.prototype.startsWith
<boolean> startsWith( <string>/<number> string )
Returns true only if the internal string/array starts with string
var words= new Words( 'is this a start or an end?' );
console.log( words.startsWith('is this a start') );
Words.prototype.endsWith
<boolean> endsWith( <string>/<number> string )
Returns true only if the internal string/array ends with string
var words= new Words( 'is this a start or an end?' );
console.log( words.endsWith('an end?') );
change log
0.2.4
Updated strings.js dependency to version 1.1.6, which includes types.js version 1.3.4.
0.2.0
Modified:
- Words.prototype.reverse() - The default reverse without arguments no longer reverses all characters. This functionality
was 100% similar to the default Strings.reverse(), so pointless to overload. Now .reverse() reverses the positions
of all words, which is more useful as addition.
Added:
- Words.prototype.startsWith()
- Words.prototype.endsWith()
Don't mind the version please, as for every typo in the readme I have to bump the version for npm..
0.1.2
words.js now depends on strings.js version 1.1.4.. strings.js now includes types.js version 1.2.8, which is
improved with force'Type'. Check types.js in the phazelift repo for changes and API.
Words.prototype.find only finds words now, use Strings.find for finding characters in words.
Words.prototype.remove(0) has been removed as an option to clear the internal array. Not a big thing, I just thought
that we have .clear() for that, so it felt a bit confusing and redundant.
The manual is now more complete and up to date.
Next up are the Jasmine tests!