words.js

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');
// to have the non-overloaded strings.js, but also the handy types.js
// functions available as well use:
var Types	= require('words.js').Types;
var Strings	= require('words.js').Strings;
// or
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.$ );
// numbers and strings accepted 123 not objects, arrays etc.. they are simply ignored..

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 );
// 3

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.$ );
// numbers and strings accepted 123 not objects, arrays etc.. they are simply ignored..

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) );
// specific need

Words.prototype.$

$

A getter for .get()

var words= new Words('fetch the whole string with a getter');
console.log( words.$ );
// fetch the whole string with a getter

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.

// dispose all words longer than 4 characters
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.$ );
// of more than 4 will be

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.$ );
// or *marked* words in a string

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') );
// [2, 4]

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).$ );
// you can be very specific with UPPER and LOWERCASE

var words= new Words('you can be very specific with upper and lowercase');
console.log( words.upper(0, 1, -1).$ );
// YoU CaN BE VerY SpecifiC WitH UppeR AnD LowercasE

var words= new Words('shout it all out!');
console.log( words.upper().$ );
// SHOUT IT ALL OUT!

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().$ );
// positions words reverse

var words= new Words('words are reversed in place when 0 is given');
console.log( words.reverse(0).$ );
// sdrow era desrever ni ecalp nehw 0 si nevig

var words= new Words('any reason to reverse a specific word?');
console.log( words.reverse(1, -1, -2).$ );
// yna reason to reverse a cificeps ?drow

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.

// pseudo random, it should be extremely rare to see the same results on any run!

var words= new Words('let\'s mess up this sentence');
console.log( words.shuffle().$ );
// sentence let's up mess this

var words= new Words('or mess it up totally in place');
console.log( words.shuffle(0).$ );
// ro esms it up ltlotay ni eclpa

var words= new Words('let\'s shuffle some specific words');
console.log( words.shuffle(2, -1).$ );
// let's efsfluh some specific srowd

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).$ );
// removing is easy

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).$ );
// pop means: remove words from the end

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' ).$ );
// push means: add to the end of this 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).$ );
// remove words from the start

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:').$ );
// unshift means: adding words to the start of a string

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' ).$ );
// insert a specific word in this string

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').$ );
// to be or not to 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().$ );
// actually funny is really testing words

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') );
// true

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?') );
// true

---

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!

---