@debonet/mdarray

    1.0.4 • Public • Published

    MDArray

    Multidimensional arrays for JS

    Installation

    npm install @debonet/mdarray

    Usage

    MDArray makes working with multidimensional array structures easy and natural.

    creation

    A multidimensional array can be easily created:

    	const myMDArray = new MDArray(2,3,4);

    access

    accesing elements can be done in numerous ways:

    	// arrays can be access in typical way
    	myMDArray[1][2][3] = "hello";
    	
    	// or, equivalently
    	myMDArray[ [1,2,3] ] = "hello";
    	
    	// or, for higher performance
    	myMDArray.get( [1,2,3] ) = "hello";
    	
    	// better error handling
    	myMDArray[100][2][3] = undefined; // does not throw!
    	

    looping

    Looping is also vastly simplified. Looping over indicies:

    	for ( const index of myMDArray.loop()){
    		myMDArray[ index ] = index.join('');
    	}

    Result:

    	MDArray(2) [  
    		MDArray(3) [  
    			MDArray(4) [ '000', '001', '002', '003' ],  
    			MDArray(4) [ '010', '011', '012', '013' ],  
    			MDArray(4) [ '020', '021', '022', '023' ]  
    		],  
     		MDArray(3) [  
    			MDArray(4) [ '100', '101', '102', '103' ],  
    			MDArray(4) [ '110', '111', '112', '113' ],  
    			MDArray(4) [ '120', '121', '122', '123' ]  
    		]  
    	]  
    

    And looping over values:

    	for ( const val of myMDArray ){
    		console.log( val );
    	}

    Result:

      	000
      	001
      	002
      	003
      	010
      	011
           .
           .
           .
      	122
      	123
    

    sub-arrays

    	const myMDArray = new MDArray(2,3,4).fill(0);
    	myMDArray[1].fill(1);

    yields:

    	[ [ [ 0, 0, 0, 0 ],  
    	    [ 0, 0, 0, 0 ],  
    	    [ 0, 0, 0, 0 ] ],   
    	  [ [ 1, 1, 1, 1 ],   
    	    [ 1, 1, 1, 1 ],   
    	    [ 1, 1, 1, 1 ] ] ]   
    

    suite

    Much of the functionality of the native Array() class has been replicated with sensible multidimensional analogs, e.g.:

    	const myMDArray = new MDArray(2,3,4,5,6).fill("haystack");
    	myMDArray[ [ 1, 1, 1, 1, 1 ] ] = "needle";
    	
    	myMDArray.indexOf("needle") // == [ 1, 1, 1, 1, 1 ]

    More to be added in future releases.

    functional methods

    Including function-oriented programming methods, e.g.:

    	const mTwos = new MDArray(2,3,4,5,6).fill(2);
    
    	const mFours = myMDArray.map(( x ) => x * 2);

    API

    constructor

    new MDArray()

    produces an empty MDArray object, with dimension 0

    new MDArray( , []* )

    produces MDArray whose dimensions are set to the specified numbers

    new MDArray( )

    converts the array into an MDArray

    MDArray.prototype.get( index )

    index

    if the index is an array of length equal to the dimensionality of the MDArray, returns the value at the specified index where

    if the index is less than the dimensionality of the MDArray, returns the sub MDArray

    if the index is greater than than the dimensionality of the MDArray, undefined is returned.

    if the index is outsize of the size of the MDArray then undefined is returned.

    MDArray.prototype.set( index, x )

    sets the value at the specified index if the index is outsize of the size of the MDArray then undefined is returned.

    Other Methods

    These rougly replicate the Array class equivalents

    MDArray.prototype.every( f )

    returns true if f() applied to every element of the MDArray is true. Otherwise, returns false.

    MDArray.prototype.fill( x )

    fills every value of the MDArray with the provided value x

    MDArray.prototype.find( f )

    returns the first value of the MDArary for which f() applied to that value returns true.

    MDArray.prototype.findIndex( f )

    returns the index of the first value of the MDArary for which f() applied to that value returns true.

    MDArray.prototype.forEach( ... )

    MDArray.prototype.includes( ... )

    MDArray.prototype.indexOf( ... )

    MDArray.prototype.join( ... )

    MDArray.prototype.makeCopy( ... )

    MDArray.prototype.map( ... )

    MDArray.prototype.size( ... )

    MDArray.prototype.reduce( ... )

    MDArray.prototype.slice( ... )

    Element-By-Element Operators

    MDArray.prototype[ operation ] ( [ value ]* )

    operation

    Operation is one of:

    - - - -
    add sub mul div
    mod and or eq
    ne neq lt lte
    gt gte bitand bitor
    bitxor abs acos acosh
    asin asinh atan atan2
    atanh cbrt ceil clz32
    cos cosh exp expm1
    floor fround hypot imul
    log log10 log1p log2
    max min pow random
    round sign sin sinh
    sqrt tan tanh trunc

    value

    value is an MDArray, Array, or value.

    if value is an MDArray of same dimensionality of the calling MDArray, then operation is applied to the element

    if value is an MDArray of smaller dimensionality, the higher dimensionalities are ignored, resulting in repeated use of each element

    if value is an MDArray of greater dimensionality, the sub-MDArray is passed to the operator

    if value is an Array, it is treated identially to an MDArray.dimension=1, resulting in repeated use of each element along the final dimension.

    otherwise value is used in the per-element operation directly.

    MDArray.prototype.applyOperation( f, [ mdarray | array | value ]* )

    Element-By-Element Reflexive Operators

    MDArray.prototype[ reflexive-operation ] ( [ value ]* )

    reflexive-operation

    reflexive-operation is one of

    - - - -
    setToAdd setToSub setToMul setToDiv
    setToMod setToAnd setToOr setToEq
    setToNe setToNeq setToLt setToLte
    setToGt setToGte setToBitand setToBitor
    setToBitxor setToAbs setToAcos setToAcosh
    setToAsin setToAsinh setToAtan setToAtan2
    setToAtanh setToCbrt setToCeil setToClz32
    setToCos setToCosh setToExp setToExpm1
    setToFloor setToFround setToHypot setToImul
    setToLog setToLog10 setToLog1p setToLog2
    setToMax setToMin setToPow setToRandom
    setToRound setToSign setToSin setToSinh
    setToSqrt setToTan setToTanh setToTrunc

    value

    value is an MDArray, Array, or value.

    if value is an MDArray of same dimensionality of the calling MDArray, then operation is applied to the element

    if value is an MDArray of smaller dimensionality, the higher dimensionalities are ignored, resulting in repeated use of each element

    if value is an MDArray of greater dimensionality, the sub-MDArray is passed to the operator

    if value is an Array, it is treated identially to an MDArray.dimension=1, resulting in repeated use of each element along the final dimension.

    otherwise value is used in the per-element operation directly.

    MDArray.prototype.applyReflexiveOperation( f, [ mdarray | array | value ]* )

    Reductive Operators

    MDArray.prototype[ reductive-operation ] ( [ value ]* )

    . . .
    maxElt minElt sumUp
    dot dist norm
    cityDist

    value

    See above

    return

    A number

    Not yet implemented

    MDArray.prototype.splice( ... )


    Static class methods

    Element-By-Element Operators

    MDArray[ operation ] ( [ value ]* )

    operation

    Operation is one of:

    - - - -
    add sub mul div
    mod and or eq
    ne neq lt lte
    gt gte bitand bitor
    bitxor abs acos acosh
    asin asinh atan atan2
    atanh cbrt ceil clz32
    cos cosh exp expm1
    floor fround hypot imul
    log log10 log1p log2
    max min pow random
    round sign sin sinh
    sqrt tan tanh trunc

    value

    value is an MDArray, Array, or value.

    if value is an MDArray of same dimensionality of the calling MDArray, then operation is applied to the element

    if value is an MDArray of smaller dimensionality, the higher dimensionalities are ignored, resulting in repeated use of each element

    if value is an Array, it is treated identially to an MDArray.dimension=1, resulting in repeated use of each element along the final dimension. otherwise value is used in the per-element operation directly.

    returns

    Returns an MDArray containing the element-by-element result of the operation. For each of the above operations, the size of the result is determined by the MDArray argument with the highest dimension.

    e.g.

    	const mTwos = new MDArray(1,2,3).fill(2);
    	const mSevens = MDArray.sub(9, mTwos);

    MDArray.applyOperation( f, [ mdarray | array | value ]* )

    MDArray[ reductive-operation ] ( [ value ]* )

    value

    See above

    return

    A number

    Looping

    MDArray.loop( range[, range]* )

    each argument is treated as a range over which a multidimensional iteration is done.

    range

    the range can be a number, pair, or triplet. In the case of a number the range is assumed to be 0 to number with step of 1. In the case of a pair the range is assumed to be pair[0] to pair[1] with step of 1. In the case of a triplet the range is assumed to be pair[0] to pair[2] with step of pair[1];

    Example:

    	for ( const index of MDArray.loop( 3, [ 1, 4 ], [-1, -2, -5 ], )){
    		console.log("\t\t\t",index);
    	}

    output

      		 [ 0, 1, -1 ]  
      		 [ 0, 1, -3 ]  
      		 [ 0, 2, -1 ]  
      		 [ 0, 2, -3 ]  
      		 [ 0, 3, -1 ]  
      		 [ 0, 3, -3 ]  
      		 [ 1, 1, -1 ]  
      		 [ 1, 1, -3 ]  
      		 [ 1, 2, -1 ]  
      		 [ 1, 2, -3 ]  
      		 [ 1, 3, -1 ]  
      		 [ 1, 3, -3 ]  
      		 [ 2, 1, -1 ]  
      		 [ 2, 1, -3 ]  
      		 [ 2, 2, -1 ]  
      		 [ 2, 2, -3 ]  
      		 [ 2, 3, -1 ]  
      		 [ 2, 3, -3 ]  
    

    MDArray.loop( mdarray )

    mdarray

    if an MDArray is provided, the loop is over every element

    MDArray.loopAround( [, <radius = 1>] )

    iterates over the neighborhood of size radius surrounding, but not including, the indexed point. e.g.:

    	for ( const index of MDArray.loopAround( [3,4], 1 )){
    		console.log("\t\t\t",index);
    	}

    output

      		 [ 2, 3 ]  
      		 [ 2, 4 ]  
      		 [ 2, 5 ]  
      		 [ 3, 3 ]  
      		 [ 3, 5 ]  <--- notice [3, 4] does not appear  
      		 [ 4, 3 ]  
      		 [ 4, 4 ]  
      		 [ 4, 5 ]  
    

    MDArray.loopUpDown( [, <radius = 1>] )

    loops along each dimension separately, within the provided radius, e.g.:

    	for ( const index of MDArray.loopUpDown( [3,4], 2 )){
    		console.log("\t\t\t",index);
    	}

    output

      		 [ 1, 4 ] // loop 2 before in dimension 0  
      		 [ 2, 4 ]  
      		 [ 4, 4 ] // loop 2 after in dimension 0  
      		 [ 5, 4 ]  
      		 [ 3, 2 ] // loop 2 before in dimension 1  
      		 [ 3, 3 ]  
      		 [ 3, 5 ] // loop 2 after in dimension 1  
      		 [ 3, 6 ]  
    

    Install

    npm i @debonet/mdarray

    DownloadsWeekly Downloads

    4

    Version

    1.0.4

    License

    MIT

    Unpacked Size

    42.3 kB

    Total Files

    11

    Last publish

    Collaborators

    • debonet