String Array

String array class.

Why not just use native Arrays? A StringArray

prevents non-string primitives from being added to the array
provides options to constrain string length
allows fancy indexing
- fancy get
- fancy set

===

Install
Usage
- StringArray()
- Properties
- Get Methods
  - get
  - iget
  - mget
  - sget
  - reget
  - bget
  - lget
- Set Methods
  - set
  - iset
  - mset
  - sset
  - reset
  - bset
  - lset
- Mutator Methods
  - push()
  - pop()
  - unshift()
  - shift()
  - reverse()
  - sort()
  - splice()
- Accessor Methods
  - indexOf()
  - lastIndexOf()
  - slice()
  - concat()
  - join()
  - toString()
  - toLocaleString()
  - toArray()
- Iteration Methods
  - forEach()
  - every()
  - some()
  - filter()
  - map()
  - reduce()
  - reduceRight()
Examples
Notes
Tests
- Unit
- Coverage
License

===

Installation

$ npm install string-array

For use in the browser, use browserify.

Usage

var StringArray = require( 'string-array' );

StringArray( [len, opts] )

String array constructor. If provided a length len, initializes a filled StringArray of length len, where the fill values are empty strings.

var arr = new StringArray();

arr.length;
// returns 0

arr = new StringArray( 20 );

arr.length;
//returns 20

The constructor accepts an options object with the following options:

min: minimum length of a string added to the array. Default: 0.
max: maximum length of a string added to the array. Default: 2^32-1.

var opts = {
	'min': 5,
	'max': 10
};

var arr = new StringArray( opts );

// Valid string...
arr.push( 'Hello' );

// Invalid string...
arr.push( 'a' );
// throws RangeError

// Invalid string...
arr.push( 'How are you doing today?' );
// throw RangeError

===

Properties

length

Returns the number of array elements.

var arr = new StringArray();

arr.length;
// returns 0

arr.push( 'beep' );
arr.length;
// returns 1

arr.length = 0;
arr.length;
// returns 0

minLength

Specifies the minimum allowed length of strings added to the array. Default length is 0.

var arr = new StringArray();

arr.minLength;
// returns 0

// Valid string...
arr.push( 'beep' );

arr.minLength = 5;

// Invalid string...
arr.push( 'beep' );
// throws RangeError

Note: setting the minLength after elements have been added to the array does not affect the existing elements; the setting only applies to future strings added to the array.

maxLength

Specifies the maximum allowed length of strings added to the array. Default length is 2^32-1.

var arr = new StringArray();

arr.maxLength;
// returns 2^31-1

// Valid string...
arr.push( 'beep' );

arr.maxLength = 3;

// Invalid string...
arr.push( 'beep' );
// throws RangeError

Note: setting the maxLength after elements have been added to the array does not affect the existing elements; the setting only applies to future strings added to the array.

===

Get Methods

StringArray.prototype.get()

TBD.

StringArray.prototype.iget( idx )

Returns a StringArray value located at a specific index. If idx < 0, the index refers to a position relative to the StringArray end, where idx = -1 corresponds to the last element. If the input idx does not correspond to any element, the method returns undefined.

var arr = new StringArray(),
	val;

arr.push( 'a', 'b', 'c', 'd' );

val = arr.iget( 2 );
// returns 'c'

val = arr.iget( -3 );
// returns 'b'

val = arr.iget( 10 );
// returns undefined

StringArray.prototype.mget( idx[, options] )

Returns values located at specified indices in a new StringArray. If an index is < 0, the index refers to a position relative to the StringArray end.

var arr1 = new StringArray(),
	arr2;

arr1.push( 'a', 'b', 'c', 'd' );

arr2 = arr1.mget( [2,3] );
arr2.toString();
// returns 'c,d'

arr2 = arr1.mget( [-3,-4] );
arr2.toString();
// returns 'a,b'

arr2 = arr1.mget( [10,11,12] );
// returns null

If an index exceeds array dimensions, the index is ignored. If provided an empty index array or no indices correspond to StringArray values, the method returns null.

By default, duplicate indices are ignored and results are ordered by ascending index. To allow duplicate indices and to turn off sorting, set the dedupe option to false.

var arr1 = new StringArray(),
	arr2;

arr1.push( 'a', 'b', 'c', 'd' );

arr2 = arr1.mget( [2,2,1,1,1,1] );
arr2.toString();
// returns 'b,c'

arr2 = arr1.mget( [2,2,1,1,1,1], {'dedupe':false} );
arr2.toString();
// returns 'c,c,b,b,b,b'

StringArray.prototype.sget( subsequence )

Returns values in a new StringArray according to a specified subsequence. If no subsequence indices correspond to StringArray elements, the method returns null.

var arr1 = new StringArray(),
	arr2;

arr1.push( 'a', 'b', 'c', 'd', 'e', 'f' );

arr2 = arr1.sget( ':' );
arr2.toString();
// returns 'a,b,c,d,e,f'

arr2 = arr1.sget( '2:' );
arr2.toString();
// returns 'c,d,e,f'

arr2 = arr1.sget( '2:4' );
arr2.toString();
// returns 'c,d'

arr2 = arr1.sget( '2:-1' );
arr2.toString();
// returns 'c,d,e'

arr2 = arr1.sget( '2:end-1' );
arr2.toString();
// returns 'c,d,e'

arr2 = arr1.sget( '::2' );
arr2.toString();
// returns 'a,c,e'

arr2 = arr1.sget( '5::-1' );
arr2.toString();
// returns 'f,e,d,c,b,a'

arr2 = arr1.sget( '20:' );
// returns null

For further subsequence documentation, see compute-indexspace.

StringArray.prototype.reget( re )

Returns values satisfying a regular expression in a new StringArray. If no values satisfy the regular expression, the method returns null.

var arr1 = new StringArray(),
	arr2;

arr1.push( 'a', 'beep', 'boop', 'c' );

arr2 = arr1.reget( /^b.*p$/ );
arr2.toString();
// returns 'beep,boop'

arr2 = arr.reget( /^w.*t$/ );
// returns null

StringArray.prototype.bget( arr )

Returns values where the input array is equal to true in a new StringArray. If all elements in the input boolean array are false, the method returns null.

var arr1 = new StringArray(),
	arr2;

arr1.push( 'a', 'beep', 'boop', 'c' );

arr2 = arr1.bget( [true,false,true,false] );
arr2.toString();
// returns 'a,boop'

arr2 = arr.bget( [false,false,false,false] );
// returns null

The input boolean array is not required to have the same length as the StringArray. If the boolean array is shorter than the StringArray, only the first N elements are considered, where N is the input array length. If the input array length is greater than the StringArray length, only the first N elements are considered, where N is the StringArray length.

var arr1 = new StringArray(),
	arr2;

arr1.push( 'a', 'beep', 'boop', 'd' );

arr2 = arr1.bget( [false,true,true] );
arr2.toString();
// returns 'beep,boop'

arr2 = arr1.bget( [false,true,false,false,true,true] );
arr2.toString();
// returns 'beep'

StringArray.prototype.lget( arr )

Returns values where the input array is equal to 1 in a new StringArray. If all elements in the input logical array are 0, the method returns null.

var arr1 = new StringArray(),
	arr2;

arr1.push( 'a', 'beep', 'boop', 'c' );

arr2 = arr1.lget( [1,0,1,0] );
arr2.toString();
// returns 'a,boop'

arr2 = arr.lget( [0,0,0,0] );
// returns null

The input logical array is not required to have the same length as the StringArray. If the logical array is shorter than the StringArray, only the first N elements are considered, where N is the input array length. If the input array length is greater than the StringArray length, only the first N elements are considered, where N is the StringArray length.

var arr1 = new StringArray(),
	arr2;

arr1.push( 'a', 'beep', 'boop', 'd' );

arr2 = arr1.lget( [0,1,1] );
arr2.toString();
// returns 'beep,boop'

arr2 = arr1.lget( [0,1,0,0,1,1] );
arr2.toString();
// returns 'beep'

===

Set Methods

StringArray.prototype.set()

TBD.

StringArray.prototype.iset( idx, val[, thisArg] )

Sets a StringArray value located at a specified index. val may be either a string primitive or a callback function. The callback is provided two arguments:

value: value at the specified index.
idx: specified index.

The callback is expected to return a string primitive; otherwise, the method throws a TypeError.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );

arr.iset( 1, 'beep' );
arr.toString();
// returns 'a,beep,c'

arr.iset( 1, function set( d, i ) {
	console.log( this.toString() );
	// returns 'a,beep,c'
	return d.replace( /e/g, 'o' );
});
arr.toString();
// returns 'a,boop,c'

arr.iset( 4, 'e' );
arr.toString();
// returns 'a,boop,c,,e'

Negative indices are allowed, as long as they resolve to a nonnegative index; e.g., len - |idx| >= 0. If not, the method throws a RangeError.

arr.iset( -4, 'beep' );
arr.toString();
// returns 'a,beep,c,,e'

By default, the callback this context is set to the StringArray instance. To specify a different this context, provide a thisArg.

function set( d, i ) {
	console.log( this );
	// returns {}
	return d.replace( /e/g, 'o' );
}

arr.iset( 1, set, {} );
arr.toString();
// returns 'a,boop,c,,e'

Note: an input string must abide by StringArray length constraints. If an input string does not conform, the method throws a RangeError.

StringArray.prototype.mset( idx, val[, thisArg] )

Sets StringArray values located at a specified indices. val may be either a single string primitive, a string primitive array of equal length, or a callback function. The callback is provided two arguments:

value: value at the specified index.
idx: specified index.

The callback is expected to return a string primitive; otherwise, the method throws a TypeError.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );

arr.mset( [0,1], 'beep' );
arr.toString();
// returns 'beep,beep,c'

arr.mset( [0,1], function set( d, i ) {
	console.log( this.toString() );
	// returns 'beep,beep,c'
	return d.replace( /e/g, 'o' );
});
arr.toString();
// returns 'boop,boop,c'

arr.mset( [3,4], ['d','e'] );
arr.toString();
// returns 'boop,boop,c,d,e'

Negative indices are allowed, as long as they resolve to a nonnegative index; e.g., len - |idx| >= 0. If not, the method throws a RangeError.

arr.mset( [-4], 'beep' );
arr.toString();
// returns 'boop,beep,c,d,e'

By default, the callback this context is set to the StringArray instance. To specify a different this context, provide a thisArg.

function set( d, i ) {
	console.log( this );
	// returns {}
	return d.replace( /e/g, 'o' );
}

arr.mset( [0,1], set, {} );
arr.toString();
// returns 'boop,boop,c,d,e'

Notes:

all strings must abide by StringArray length constraints. If a string does not conform, the method throws a RangeError.

arr.minLength = 1;
arr.maxLength = 1;

arr.mset( [0,1,2], ['a','b','woot'] );
// throws RangeError

arr.toString();
// returns 'boop,boop,c,d,e'

setting multiple StringArray values is atomic. If setting one value fails (e.g., TypeError), all values fail to be set.

arr.mset( [0,1,2], function set( d, i ) {
	if ( i === 2 ) {
		return 5;
	}
	return d;
});
// throws TypeError

arr.toString();
// returns 'boop,boop,c,d,e'

StringArray.prototype.sset( str, val[, thisArg] )

Sets StringArray values according to a specified subsequence. val may be either a single string primitive, a string primitive array of equal length, or a callback function. The callback is provided two arguments:

value: value at a subsequence index.
idx: subsequence index.

The callback is expected to return a string primitive; otherwise, the method throws a TypeError.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );

arr.sset( ':2', 'beep' );
arr.toString();
// returns 'beep,beep,c'

arr.sset( '0:end-1:1', function set( d, i ) {
	console.log( this.toString() );
	// returns 'beep,beep,c'
	return d.replace( /e/g, 'o' );
});
arr.toString();
// returns 'boop,boop,c'

arr.sset( '3:', ['d','e'] );
arr.toString();
// returns 'boop,boop,c,d,e'

arr.sset( '::2', ['wo','ot', '!!'] );
arr.toString();
// returns 'wo,boop,ot,d,!!'

By default, the callback this context is set to the StringArray instance. To specify a different this context, provide a thisArg.

function set( d, i ) {
	console.log( this );
	// returns {}
	return d.replace( /o/g, 'e' );
}

arr.sset( '0:end-1:1', set, {} );
arr.toString();
// returns 'we,beep,et,d,!!'

For further subsequence documentation, see compute-indexspace.

Notes:

all strings must abide by StringArray length constraints. If a string does not conform, the method throws a RangeError.

arr.minLength = 1;
arr.maxLength = 1;

arr.sset( ':3', ['a','b','woot'] );
// throws RangeError

arr.toString();
// returns 'we,beep,et,d,!!'

setting multiple StringArray values is atomic. If setting one value fails (e.g., TypeError), all values fail to be set.

arr.sset( ':3', function set( d, i ) {
	if ( i === 2 ) {
		return 5;
	}
	return d;
});
// throws TypeError

arr.toString();
// returns 'we,beep,et,d,!!'

StringArray.prototype.reset( re, val[, thisArg] )

Sets StringArray elements whose values satisfy a regular expression. val may be either a string primitive or a callback function. The callback is provided two arguments:

value: value satisfying regular expression.
idx: value index.

The callback is expected to return a string primitive; otherwise, the method throws a TypeError.

var arr = new StringArray();

arr.push( 'a', 'beep', 'boop', 'c' );

arr.reset( /^b.*p$/, 'woot' );
arr.toString();
// returns 'a,woot,woot,c'

arr.reset( /^w.*/, function set( d, i ) {
	console.log( this.toString() );
	// returns 'a,woot,woot,c'
	return d.replace( /o{2}t$/, 'eep' );
});
arr.toString();
// returns 'a,weep,weep,c'

By default, the callback this context is set to the StringArray instance. To specify a different this context, provide a thisArg.

function set( d, i ) {
	console.log( this );
	// returns {}
	return d.replace( /e{2}p$/, 'oot' );
}

arr.reset( /^w.*/, set, {} );
arr.toString();
// returns 'a,woot,woot,c'

Note: an input string must abide by StringArray length constraints. If an input string does not conform, the method throws a RangeError.

StringArray.prototype.bset( arr, val[, thisArg] )

Sets StringArray values where an input boolean array is true. val may be either a single string primitive, a string primitive array of equal length, or a callback function. The callback is provided two arguments:

value: value where input array is true.
idx: value index.

The callback is expected to return a string primitive; otherwise, the method throws a TypeError.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );

arr.bset( [true,false,true], 'beep' );
arr.toString();
// returns 'beep,b,beep'

arr.bset( [true,false,true], function set( d, i ) {
	console.log( this.toString() );
	// returns 'beep,b,beep'
	return d.replace( /e/g, 'o' );
});
arr.toString();
// returns 'boop,b,boop'

arr.bset( [true,false,true], ['d','e','f'] );
arr.toString();
// returns 'd,b,f'

By default, the callback this context is set to the StringArray instance. To specify a different this context, provide a thisArg.

function set( d, i ) {
	console.log( this );
	// returns {}
	return 'a';
}

arr.bset( [true,false,false], set, {} );
arr.toString();
// returns 'a,b,f'

The input boolean array is not required to have the same length as the StringArray. If the boolean array is shorter than the StringArray, only the first N elements are considered, where N is the input array length. If the input array length is greater than the StringArray length, each array element equal to true extends the StringArray.

arr.bset( [false,false,false,false,true,false,true], 'woot' );
arr.toString();
// returns 'a,b,f,,woot,,woot'

arr.bset( [true,true], ['beep','boop'] );
arr.toString();
// returns 'beep,boop,f,,woot,,woot'

Notes:

all strings must abide by StringArray length constraints. If a string does not conform, the method throws a RangeError.

var arr = new StringArray();

arr.push( 'd', 'b', 'f' );
arr.minLength = 1;
arr.maxLength = 1;

arr.bset( [true,true,true], ['a','e','woot'] );
// throws RangeError

arr.toString();
// returns 'd,b,f'

setting multiple StringArray values is atomic. If setting one value fails (e.g., TypeError), all values fail to be set.

arr.bset( [true,true,true], function set( d, i ) {
	if ( i === 2 ) {
		return 5;
	}
	return d;
});
// throws TypeError

arr.toString();
// returns 'd,b,f'

StringArray.prototype.lset( arr, val[, thisArg] )

Sets StringArray values where an input logical array is 1. val may be either a single string primitive, a string primitive array of equal length, or a callback function. The callback is provided two arguments:

value: value where input array is 1.
idx: value index.

The callback is expected to return a string primitive; otherwise, the method throws a TypeError.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );

arr.lset( [1,0,1], 'beep' );
arr.toString();
// returns 'beep,b,beep'

arr.lset( [1,0,1], function set( d, i ) {
	console.log( this.toString() );
	// returns 'beep,b,beep'
	return d.replace( /e/g, 'o' );
});
arr.toString();
// returns 'boop,b,boop'

arr.lset( [1,0,1], ['d','e','f'] );
arr.toString();
// returns 'd,b,f'

By default, the callback this context is set to the StringArray instance. To specify a different this context, provide a thisArg.

function set( d, i ) {
	console.log( this );
	// returns {}
	return 'boop';
}

arr.lset( [1,0,1], set, {} );
arr.toString();
// returns 'boop,b,boop'

The input logical array is not required to have the same length as the StringArray. If the logical array is shorter than the StringArray, only the first N elements are considered, where N is the input array length. If the input array length is greater than the StringArray length, each array element equal to 1 extends the StringArray.

arr.lset( [0,0,0,0,1,0,1], 'woot' );
arr.toString();
// returns 'boop,b,boop,,woot,,woot'

arr.lset( [1,1], ['beep','bop'] );
arr.toString();
// returns 'beep,bop,boop,,woot,,woot'

Notes:

all strings must abide by StringArray length constraints. If a string does not conform, the method throws a RangeError.

var arr = new StringArray();

arr.push( 'd', 'b', 'f' );
arr.minLength = 1;
arr.maxLength = 1;

arr.lset( [1,1,1], ['a','e','woot'] );
// throws RangeError

arr.toString();
// returns 'd,b,f'

setting multiple StringArray values is atomic. If setting one value fails (e.g., TypeError), all values fail to be set.

arr.lset( [1,1,1], function set( d, i ) {
	if ( i === 2 ) {
		return 5;
	}
	return d;
});
// throws TypeError

arr.toString();
// returns 'd,b,f'

===

Mutator Methods

StringArray.prototype.push( string0[, string1[,...]] )

Adds one or more elements to the end of an array and returns the new array length.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
// returns 3

arr.toString();
// returns 'a,b,c'

arr.push( 'd' );
// returns 4

arr.toString();
// returns 'a,b,c,d'

StringArray.prototype.pop()

Removes the last array element and returns that element.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.toString();
// returns 'a,b,c'

arr.pop();
// returns 'c'

arr.toString();
// returns 'a,b'

StringArray.prototype.unshift( string0[, string1[,...]] )

Adds one or more elements to the front of an array and returns the new array length.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
// returns 3

arr.toString();
// returns 'a,b,c'

arr.unshift( 'd' );
// returns 4

arr.toString();
// returns 'd,a,b,c'

StringArray.prototype.shift()

Removes the first array element and returns that element.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.toString();
// returns 'a,b,c'

arr.shift();
// returns 'a'

arr.toString();
// returns 'b,c'

StringArray.prototype.reverse()

Reverses the array order.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.toString();
// returns 'a,b,c'

arr.reverse();
arr.toString();
// returns 'c,b,a'

StringArray.prototype.sort( [comparator] )

Sorts the array elements in place.

var arr = new StringArray();

function descending( a, b ) {
	if ( a < b ) {
		return 1;
	}
	if ( a > b ) {
		return -1;
	}
	return 0;
}

arr.push( 'a', 'b', 'c' );
arr.toString();
// returns 'a,b,c'

arr.sort( descending );
arr.toString();
// returns 'c,b,a'

StringArray.prototype.splice( start, deleteCount[, string0[, string1[,...]]] )

Adds and/or removes array elements and returns any removed elements,

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.toString();
// returns 'a,b,c'

arr.splice( 1, 1 );
// returns ['b']

arr.toString();
// returns 'a,c'

arr.splice( 1, 0, 'b' );
// returns []

arr.toString();
// returns 'a,b,c'

===

Accessor Methods

StringArray.prototype.indexOf( [str] )

Returns the first index of a StringArray value equal to a specified value. Returns -1 if not found.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.indexOf( 'b' );
// returns 1

arr.indexOf( 'd' );
// returns -1

StringArray.prototype.lastIndexOf( [str] )

Returns the last index of a StringArray value equal to a specified value. Returns -1 if not found.

var arr = new StringArray();

arr.push( 'a', 'b', 'b', 'c' );
arr.lastIndexOf( 'b' );
// returns 2

arr.lastIndexOf( 'd' );
// returns -1

StringArray.prototype.slice( [start[, end]] )

Extracts a section of a StringArray into a new StringArray. If not provided, start defaults to 0 and end defaults to the array length.

var arr = new StringArray(),
	slice;

arr.push( 'a', 'b', 'c', 'd', 'e' );

slice = arr.slice();
slice.toString();
// returns 'a,b,c,d,e'

slice = arr.slice( 2 );
slice.toString();
// returns 'c,d,e'

slice = arr.slice( -3 );
slice.toString();
// returns 'b,c,d,e'

slice = arr.slice( 1, 3 );
slice.toString();
// returns 'b,c'

slice = arr.slice( 1, -1 );
slice.toString();
// returns 'b,c,d'

Note: returns a new StringArray with the same string length constraints.

StringArray.prototype.concat( value0[, value1[,...]] )

Concatenates this StringArray with other StringArray(s), array(s) of strings, and/or string(s).

var arr1 = new StringArray(),
	arr2 = new StringArray();

arr1.push( 'a', 'b', 'c' );
arr2.push( 'd', 'e', 'f' );

var arr3 = arr1.concat( arr2 );

arr3 instanceof StringArray;
// returns true

arr3.toString();
// returns 'a,b,c,d,e,f'

var arr4 = arr3.concat( 'beep' );
arr4.toString();
// returns 'a,b,c,d,e,f,beep'

var arr5 = arr1.concat( 'd', ['e','f'] );
arr5.toString();
// returns 'a,b,c,d,e,f'

Note: returns a new StringArray with the same string length constraints.

StringArray.prototype.join( [sep] )

Joins all StringArray values into a single string. The default value separator is ','.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.join();
// returns 'a,b,c'

To specify a different separator,

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.join( ' - ' );
// returns 'a - b - c'

StringArray.prototype.toString()

Returns a string representation of a StringArray.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.toString();
// returns 'a,b,c'

StringArray.prototype.toLocaleString()

Returns a locale specific string representation of a StringArray.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.toLocaleString();
// returns 'a,b,c'

StringArray.prototype.toArray()

Returns a native array representation of a StringArray.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.toArray();
// returns ['a','b','c']

Note: changes to the returned array will not affect the StringArray.

===

Iteration Methods

StringArray.prototype.forEach( clbk[, thisArg] )

Executes a provided function once for every StringArray element. The clbk is provided the following arguments:

value: current element
index: current element index
arr: StringArray instance

To specify the runtime this context for the callback, provide a thisArg.

var arr = new StringArray();
arr.push( 'a', 'b', 'c' );

arr.forEach( function forEach( val, i, arr ) {
	console.log( 'Value at index `' + i + '` is `' + val + '`.' );
});

Note: do not use this as a general method. Instead, use Array.prototype.forEach.call() when wanting to apply to non-StringArray objects.

StringArray.prototype.every( clbk[, thisArg] )

Returns true if every element passes a provided condition; otherwise, false. The condition clbk is provided the following arguments:

value: current element
index: current element index
arr: StringArray instance

To specify the runtime this context for the callback, provide a thisArg.

var arr = new StringArray();
arr.push( 'a', 'b', 'c' );

var bool = arr.every( function every( val, i, arr ) {
	return ( val.length < 3 );
});
// returns true

Note: do not use this as a general method. Instead, use Array.prototype.every.call() when wanting to apply to non-StringArray objects.

StringArray.prototype.some( clbk[, thisArg] )

Returns true if at least one element passes a provided condition; otherwise, false. The condition clbk is provided the following arguments:

value: current element
index: current element index
arr: StringArray instance

To specify the runtime this context for the callback, provide a thisArg.

var arr = new StringArray();
arr.push( 'a', 'beep', 'c' );

var bool = arr.some( function some( val, i, arr ) {
	return ( val.length > 1 );
});
// returns true

Note: do not use this as a general method. Instead, use Array.prototype.some.call() when wanting to apply to non-StringArray objects.

StringArray.prototype.filter( clbk[, thisArg] )

Returns a new StringArray containing only those elements which satisfy a test condition. The condition clbk is provided the following arguments:

value: current element
index: current element index
arr: StringArray instance

To specify the runtime this context for the callback, provide a thisArg.

var arr = new StringArray();
arr.push( 'a', 'beep', 'boop', 'c' );

var arr2 = arr.filter( function filter( val, i, arr ) {
	return ( val.length > 1 );
});
arr2.toString();
// returns 'beep,boop'

Notes:

do not use this as a general method. Instead, use Array.prototype.filter.call() when wanting to apply to non-StringArray objects.
returns a new StringArray instance having the same length constraints.

StringArray.prototype.map( clbk[, thisArg] )

Applies a function to each StringArray element and maps the result of each invocation to an element in a new StringArray. The clbk is provided the following arguments:

value: current element
index: current element index
arr: StringArray instance

To specify the runtime this context for the callback, provide a thisArg.

var arr = new StringArray();
arr.push( 'a', 'beep', 'boop', 'c' );

var arr2 = arr.map( function map( val, i, arr ) {
	return val + '-bot';
});
arr2.toString();
// returns 'a-bot,beep-bot,boop-bot,c-bot'

Notes:

the map function should return only string primitives. A non-string primitive result will throw an Error.
do not use this as a general method. Instead, use Array.prototype.map.call() when wanting to apply to non-StringArray objects.
returns a new StringArray instance having no length constraints.

StringArray.prototype.reduce( clbk[, initialValue] )

Executes a function against an accumulator and each StringArray element to return a single value. The clbk is provided the following arguments:

acc: previous reduce result
curr: current element
index: current element index
arr: StringArray instance

To specify an initial value, provide a second argument.

var arr = new StringArray();
arr.push( 'a', 'b', 'c' );

var result = arr.reduce( function reduce( acc, val, i, arr ) {
	return acc + val + val;
});
// returns 'aabbcc'

Notes: do not use this as a general method. Instead, use Array.prototype.reduce.call() when wanting to apply to non-StringArray objects.

StringArray.prototype.reduceRight( clbk[, initialValue] )

Executes a function against an accumulator and each StringArray element to return a single value. The order in which elements are processed proceeds from the end of the StringArray to the start of the StringArray.The clbk is provided the following arguments:

acc: previous reduce result
curr: current element
index: current element index
arr: StringArray instance

To specify an initial value, provide a second argument.

var arr = new StringArray();
arr.push( 'a', 'b', 'c' );

var result = arr.reduceRight( function reduce( acc, val, i, arr ) {
	return acc + val + val;
});
// returns 'ccbbaa'

Notes: do not use this as a general method. Instead, use Array.prototype.reduceRight.call() when wanting to apply to non-StringArray objects.

===

Examples

var StringArray = require( 'string-array' );

var arr, val, bool;

arr = new StringArray();

arr.push( 'a', 'b', 'c' );
arr.length;
// returns 3

arr.toString();
// returns 'a,b,c'

val = arr.pop();
// returns 'c'

val = arr.shift();
// returns 'a'

arr.unshift( 'c' );
arr.length;
// returns 2

arr.toString();
// returns 'c,b'

arr.splice( 0, 0, 'd', 'e', 'f' );
arr.length;
// returns 5

arr.toString();
// returns 'c,d,e,f,b'

val = arr.slice( 1, -1 );
// returns 'd,e,f'

arr.forEach( function forEach( val, i ) {
	console.log( i, val );
});

arr.sort();
arr.toString();
// returns 'b,c,d,e,f'

arr.reverse();
arr.toString();
// returns 'f,e,d,c,b'

bool = arr.every( function every( val, i ) {
	return ( val < 'g' );
});
// returns true

bool = arr.some( function some( val, i ) {
	return ( val >= 'c' );
});
// returns true

val = arr.filter( function filter( val ) {
	return 'f' > val && val > 'b';
});
val.toString();
// returns 'e,d,c'

val = arr.map( function map( val, i ) {
	var str = val;
	for ( var j = 0; j < i; j++ ) {
		val += str;
	}
	return val;
});
val.toString();
// returns 'f,ee,ddd,cccc,bbbbb'

val = arr.reduce( function reduce( acc, curr ) {
	return acc + '-|-' + curr;
});
// returns 'f-|-e-|-d-|-c-|-b'

val = arr.reduceRight( function reduce( acc, curr ) {
	return acc + '-|-' + curr;
});
// returns 'b-|-c-|-d-|-e-|-f'


// GET //

val = arr.iget( 1 );
// returns 'e'

val = arr.mget( [1,3] );
val.toString();
// returns 'e,c'

val = arr.bget( [true,false,true,true,false] );
val.toString();
// returns 'f,d,c'

val = arr.lget( [1,0,1,1,0] );
val.toString();
// returns 'f,d,c'

val = arr.reget( /[bdf]/ );
val.toString();
// returns 'f,d,b'


// SET //

arr.iset( 1, 'eep' );
arr.toString();
// returns 'f,eep,d,c,b'

arr.mset( [0,2], ['foo','bar'] );
arr.toString();
// returns 'foo,eep,bar,c,b'

arr.bset( [false,false,false,true,true], function set( d ) {
	return d + d;
});
arr.toString();
// returns 'foo,eep,bar,cc,bb'

arr.lset( [1,1,1], function set( d ) {
	return '~' + d + '~';
});
arr.toString();
// returns '~foo~,~eep~,~bar~,cc,bb'

arr.reset( /^~.*~$/, function set( d ) {
	return d.replace( /^~(.*)~$/, '$1' );
});
arr.toString();
// returns 'foo,eep,bar,cc,bb'

To run the example code from the top-level application directory,

$ node ./examples/index.js

===

Notes

A StringArray is not an Array instance.
Object.keys() will not work as expected. A StringArray instance is an object which manages an internal array.
When applied to a StringArray, Array.isArray() will return false.
While an effort has been made to retain fidelity to the ECMAScript standard for Arrays, no guarantee is made that method implementations are spec compliant. This is particularly the case where the spec stipulates additional checks, etc; e.g., Array#reverse.
A sparse StringArray is not allowed. A StringArray is always dense. When initializing a new StringArray of a specified length, the array is filled with empty strings. Additionally, when setting array indices greater than the existing length, any holes are filled with empty strings. Accordingly, StringArray methods, such as filter, map, some, every, etc, will always iterate over the entire StringArray.
[] notation does not work as expected. A StringArray is an object. Using bracket notation will set and return values on the StringArray itself, not on the internally managed array instance. You can set properties directly on the StringArray as you can with any object; just ensure that this is treated as distinct from the StringArray array data.

Working with external methods expecting native arrays will require marshalling and unmarshalling of StringArray data to and from arrays.

var arr = new StringArray();

arr.push( 'a', 'b', 'c' );

// Some method expecting native arrays...
var nativeArray = foo( arr.toArray() );

// Assuming the native array elements are all strings, marshal the data back into a string array...
arr = new StringArray();
arr.push.apply( arr, nativeArray );

===

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

License

MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
examples		examples
lib		lib
test		test
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.jshintignore		.jshintignore
.jshintrc		.jshintrc
.npmignore		.npmignore
.travis.yml		.travis.yml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TODO.md		TODO.md
package.json		package.json

License

dstructs/string-array

Folders and files

Latest commit

History

Repository files navigation

String Array

Installation

Usage

StringArray( [len, opts] )

Properties

minLength

maxLength

Get Methods

StringArray.prototype.get()

StringArray.prototype.iget( idx )

StringArray.prototype.mget( idx[, options] )

StringArray.prototype.sget( subsequence )

StringArray.prototype.reget( re )

StringArray.prototype.bget( arr )

StringArray.prototype.lget( arr )

Set Methods

StringArray.prototype.set()

StringArray.prototype.iset( idx, val[, thisArg] )

StringArray.prototype.mset( idx, val[, thisArg] )

StringArray.prototype.sset( str, val[, thisArg] )

StringArray.prototype.reset( re, val[, thisArg] )

StringArray.prototype.bset( arr, val[, thisArg] )

StringArray.prototype.lset( arr, val[, thisArg] )

Mutator Methods

Accessor Methods

StringArray.prototype.toArray()

Iteration Methods

Examples

Notes

Tests

Unit

Test Coverage

License

Copyright

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Languages