Difference between revisions of "Cabal Common Library Doc Functions"

From Elite Wiki
m (added strAddAlignedText, strAddEdgeText, strAddIndentedText, strAdd2Columns and strAdd3Columns)
m (added updateGalaxyStats())
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
This is the main class for the helper library with its members and part of the [[Cabal_Common_Library]]. Scripts can instantiate a copy, e.g.
+
This is the main class for the helper library with its members and part of the [[Cabal_Common_Library]].
{{CodeEx|codeex=this.myHelper = new worldScripts.Cabal_Common_Functions.Cabal_Common();}}
+
 
Versions before v1.6 have used <code>this.myHelper = new Cabal_Common_2DCollision();</code>
+
Scripts can instantiate a copy of the API, e.g.
 +
  this.myHelper = new worldScripts.Cabal_Common_Functions.Cabal_Common();
 +
Versions before v1.6 have used <code>this.myHelper = new Cabal_Common();</code>
 +
 
 +
 
 +
{{AV|1.8}}
 +
 
 +
A convenience instance is created and can be used directly. This is specially useful if you only need a small part of the library.
 +
  worldScripts.Cabal_Common_Functions.helper.getType(obj);
 +
 
 +
The Profiler boxes will give you a quick overview about runtimes. Times are measured with the listed examples on a Core2Duo @2GHz.
  
The Profiler boxes will give you a quick overview about runtimes. Times are measured with the listed examples.
 
  
 
== Properties ==
 
== Properties ==
 
=== internalVersion ===
 
=== internalVersion ===
 
Number. Property to give OXPs a chance to check the required lib min. version easily. This number will be raised with every release.
 
Number. Property to give OXPs a chance to check the required lib min. version easily. This number will be raised with every release.
{{CodeEx|codeex=var a = this.myHelper.internalVersion;
+
  var a = worldScripts.Cabal_Common_Functions.internalVersion;
a -> {{CCL_Int}}}}
+
The property is available in the API as well.
 +
  var a = this.myHelper.internalVersion;
 +
 
 +
Current version is {{CodeEx|codeex={{CCL_Int}}}}
  
== Methods ==
+
 
 +
== API Methods ==
 
=== baseChange() ===
 
=== baseChange() ===
{{CodeEx|codeex=baseChange: function(n, to, from )}}
+
{{CodeEx|codeex=baseChange: function( n, to, from )}}
 
{{CodeExTime|native=0.000038|extension=0.000012|js=0.000067}}
 
{{CodeExTime|native=0.000038|extension=0.000012|js=0.000067}}
 
Changes the base of n.
 
Changes the base of n.
Line 26: Line 39:
 
:;str: String. Base changed.
 
:;str: String. Base changed.
  
{{CodeEx|codeex=var a = this.myHelper.baseChange(10, 16); // convert decimal 10 to hex
+
  var a = this.myHelper.baseChange(10, 16); // convert decimal 10 to hex
var b = this.myHelper.baseChange(0xA, 2); // convert hex 0xA (10) to binary<br>
+
  var b = this.myHelper.baseChange(0xA, 2); // convert hex 0xA (10) to binary
var c = this.myHelper.baseChange('a', 2, 16); // alternative convert hex 0xA to binary<br>
+
  var c = this.myHelper.baseChange('a', 2, 16); // alternative convert hex 0xA to binary
a -> 'a', b -> '1010', c -> '1010'}}
+
  a -> 'a', b -> '1010', c -> '1010'
  
 
Author: Dr.J R Stockton.
 
Author: Dr.J R Stockton.
Line 35: Line 48:
  
 
=== clamp() ===
 
=== clamp() ===
{{CodeEx|codeex=clamp: function(value, max, min )}}
+
{{CodeEx|codeex=clamp: function( value, max, min )}}
 
{{CodeExTime|native=0.000041|extension=0.000012|js=0.000069}}
 
{{CodeExTime|native=0.000041|extension=0.000012|js=0.000069}}
 
Clamps value to max...min.
 
Clamps value to max...min.
+
 
 
'''Paramaters:'''
 
'''Paramaters:'''
 
:;value:Number. To be clamped.
 
:;value:Number. To be clamped.
Line 47: Line 60:
 
:;n:Number. Clamped.
 
:;n:Number. Clamped.
  
{{CodeEx|codeex=var a = this.myHelper.clamp(Math.random(),0.6,0.2);
+
  var a = this.myHelper.clamp(Math.random(),0.6,0.2);
a -> 0.2}}
+
  a -> 0.2
 +
 
 +
 
 +
=== getType() ===
 +
{{CodeEx|codeex=getType: function( what )  {{AV|1.8}} }}
 +
{{CodeExTime|native=0.000040|extension=0.000010|js=0.000062}}
 +
Returns lowercase string with the type or null.
 +
 
 +
'''Parameters:'''
 +
:;what:Object. To be evaluated.
 +
 
 +
'''Returns:'''
 +
:;type:String or null. If String 'array', 'boolean', 'date', 'function', 'number', 'object', 'regexp', 'string', or 'undefined'
 +
 
 +
  var a = this.myHelper.getType("A");
 +
  a -> "string"
  
  
Line 62: Line 90:
 
:;n:Number. The position of the most significant bit or 0 (zero).
 
:;n:Number. The position of the most significant bit or 0 (zero).
  
{{CodeEx|codeex=var a = this.myHelper.msbPos(25);
+
  var a = this.myHelper.msbPos(25);
a -> 5}}
+
  a -> 5
  
 
Author: Dr.J R Stockton.
 
Author: Dr.J R Stockton.
Line 72: Line 100:
 
{{CodeExTime|native=0.000038|extension=0.000010|js=0.000062}}
 
{{CodeExTime|native=0.000038|extension=0.000010|js=0.000062}}
 
Returns number of bits set in n. If n<0 a bitwise NOT will be applied before execution.
 
Returns number of bits set in n. If n<0 a bitwise NOT will be applied before execution.
+
 
 
'''Parameters:'''
 
'''Parameters:'''
 
:;n:Number. To be evaluated.
 
:;n:Number. To be evaluated.
Line 78: Line 106:
 
'''Returns:'''
 
'''Returns:'''
 
:;e:Number. The counted number of bits set to 1.
 
:;e:Number. The counted number of bits set to 1.
{{CodeEx|codeex=var a = this.myHelper.nBitsUsed(13);
+
 
a -> 3}}
+
  var a = this.myHelper.nBitsUsed(13);
 +
  a -> 3
  
  
Line 86: Line 115:
 
{{CodeExTime|native=0.000041|extension=0.000010|js=0.000069}}
 
{{CodeExTime|native=0.000041|extension=0.000010|js=0.000069}}
 
Returns rounded number with specified precision.
 
Returns rounded number with specified precision.
+
 
 
'''Parameters:'''
 
'''Parameters:'''
 
:;x:Number. To be rounded.
 
:;x:Number. To be rounded.
Line 93: Line 122:
 
'''Returns:'''
 
'''Returns:'''
 
:;e:Number. The rounded number.
 
:;e:Number. The rounded number.
{{CodeEx|codeex=var a = this.myHelper.num2Prec(25.06532123,3);
+
 
a -> 25.065}}
+
  var a = this.myHelper.num2Prec(25.06532123,3);
 +
  a -> 25.065
  
  
Line 100: Line 130:
 
{{CodeEx|codeex=pseudoRand: function( salt, mode )}}
 
{{CodeEx|codeex=pseudoRand: function( salt, mode )}}
 
{{CodeExTime|native=0.000041|extension=0.000017|js=0.000106}}
 
{{CodeExTime|native=0.000041|extension=0.000017|js=0.000106}}
LCG (Linear congruential generator) pseudo-random number generator with salt (and pepper). Can be used to generate deterministic unique values, e.g. to decide if a specific entity should be spawned.
+
LCG (Linear congruential generator) pseudo-random number generator with salt (and pepper). Can be used to generate deterministic unique values, e.g. to decide if a specific entity should be spawned.
  
 
'''Parameters:'''
 
'''Parameters:'''
Line 111: Line 141:
 
* mode.  In range 0...100.
 
* mode.  In range 0...100.
  
{{CodeEx|codeex=var test = this.myHelper.pseudoRand(55);
+
  var test = this.myHelper.pseudoRand(55);
test -> 0.11969016003422439
+
  test -> 0.11969016003422439
  
var test = this.myHelper.pseudoRand(55,true);<br>
+
  var test = this.myHelper.pseudoRand(55,true);
test -> 11}}
+
  test -> 11
  
 
Author: Jens Ayrton (Ahruman).
 
Author: Jens Ayrton (Ahruman).
Line 131: Line 161:
 
:;n:Number. Returns the random Number.
 
:;n:Number. Returns the random Number.
  
{{CodeEx|codeex=var crc = this.myHelper.rand(35);
+
  var crc = this.myHelper.rand(35);
crc -> 12}}
+
  crc -> 12
  
 
Author: Dr.J R Stockton.
 
Author: Dr.J R Stockton.
Line 149: Line 179:
 
:;n:Number. The newly generated random Number.
 
:;n:Number. The newly generated random Number.
  
{{CodeEx|codeex=var crc = this.myHelper.randSpan(35,88);
+
  var crc = this.myHelper.randSpan(35,88);
crc -> 55}}
+
  crc -> 55
  
 
Author: Dr.J R Stockton.
 
Author: Dr.J R Stockton.
Line 156: Line 186:
  
 
=== strAddAlignedText() ===
 
=== strAddAlignedText() ===
{{CodeEx|codeex=strAddAlignedText: function( text, alignment )}}
+
{{CodeEx|codeex=strAddAlignedText: function( text, alignment ) {{AV|1.6.1}} }}
 
{{CodeExTime|native=0.000122|extension=0.000028|js=0.000082}}
 
{{CodeExTime|native=0.000122|extension=0.000028|js=0.000082}}
 
Returns padded text for a single line.
 
Returns padded text for a single line.
Line 168: Line 198:
  
 
Author: Thargoid.
 
Author: Thargoid.
(New in v1.6.1)
 
  
  
 
=== strAddEdgeText() ===
 
=== strAddEdgeText() ===
{{CodeEx|codeex=strAddEdgeText: function( leftText, rightText )}}
+
{{CodeEx|codeex=strAddEdgeText: function( leftText, rightText ) {{AV|1.6.1}} }}
 
{{CodeExTime|native=0.000159|extension=0.000040|js=0.000295}}
 
{{CodeExTime|native=0.000159|extension=0.000040|js=0.000295}}
 
Returns two edge-aligned columns, one on the left and the other on the right for a single line.
 
Returns two edge-aligned columns, one on the left and the other on the right for a single line.
Line 184: Line 213:
  
 
Author: Thargoid.
 
Author: Thargoid.
(New in v1.6.1)
 
  
  
 
=== strAddIndentedText() ===
 
=== strAddIndentedText() ===
{{CodeEx|codeex=strAddIndentedText: function( text, indent )}}
+
{{CodeEx|codeex=strAddIndentedText: function( text, indent ) {{AV|1.6.1}} }}
 
{{CodeExTime|native=0.000112|extension=0.000028|js=0.000133}}
 
{{CodeExTime|native=0.000112|extension=0.000028|js=0.000133}}
 
Returns indented line of text by the given distance (in ems) from the left.
 
Returns indented line of text by the given distance (in ems) from the left.
Line 200: Line 228:
  
 
Author: Thargoid.
 
Author: Thargoid.
(New in v1.6.1)
+
 
  
 
=== strAdd2Columns() ===
 
=== strAdd2Columns() ===
{{CodeEx|codeex=strAdd2Columns: function( leftText, leftIndent, rightText, rightIndent )}}
+
{{CodeEx|codeex=strAdd2Columns: function( leftText, leftIndent, rightText, rightIndent ) {{AV|1.6.1}} }}
 
{{CodeExTime|native=0.000137|extension=0.000057|js=0.000414}}
 
{{CodeExTime|native=0.000137|extension=0.000057|js=0.000414}}
 
Returns single line text with two columns indented from the left margin by the given amount (in ems, 0-32).
 
Returns single line text with two columns indented from the left margin by the given amount (in ems, 0-32).
Line 217: Line 245:
  
 
Author: Thargoid.
 
Author: Thargoid.
(New in v1.6.1)
+
 
  
 
=== strAdd3Columns() ===
 
=== strAdd3Columns() ===
{{CodeEx|codeex=strAdd3Columns: function( leftText, leftIndent, centreText, centreIndent, rightText, rightIndent )}}
+
{{CodeEx|codeex=strAdd3Columns: function( leftText, leftIndent, centreText, centreIndent, rightText, rightIndent ) {{AV|1.6.1}} }}
 
{{CodeExTime|native=0.000041|extension=0.000013|js=0.000366}}
 
{{CodeExTime|native=0.000041|extension=0.000013|js=0.000366}}
 
Returns single line text with three columns, left, centre and right.
 
Returns single line text with three columns, left, centre and right.
Line 236: Line 264:
  
 
Author: Thargoid.
 
Author: Thargoid.
(New in v1.6.1)
 
  
  
 
=== strCompareVersion() ===
 
=== strCompareVersion() ===
 
{{CodeEx|codeex=strCompareVersion: function( strA, strB )}}
 
{{CodeEx|codeex=strCompareVersion: function( strA, strB )}}
{{CodeExTime|native=0.000037|extension=0.000012|js=0.000087}}
+
{{CodeExTime|native=0.000033|extension=0.000010|js=0.000080}}
 
Compares version strings (like “2.0.3”) against each other and returns number. It also strips pre/suffixes like “Build” or “Beta”.  Subroutine from oxpVersionTest() and oxpVersionTest2Array(), but can also be used directly.
 
Compares version strings (like “2.0.3”) against each other and returns number. It also strips pre/suffixes like “Build” or “Beta”.  Subroutine from oxpVersionTest() and oxpVersionTest2Array(), but can also be used directly.
  
Line 253: Line 280:
 
* 2 - Number.  If strA > strB
 
* 2 - Number.  If strA > strB
  
{{CodeEx|codeex=var check =  this.myHelper.strCompareVersion("Beta2.1","1.0.7");
+
  var check =  this.myHelper.strCompareVersion("Beta2.1","1.0.7");
check -> 2}}
+
  check -> 2
  
  
Line 261: Line 288:
 
{{CodeExTime|native=0.000038|extension=0.000011|js=0.000067}}
 
{{CodeExTime|native=0.000038|extension=0.000011|js=0.000067}}
 
Takes an integer number of minutes and converts it into a string. The returned string has the form 'd' days, 'h' hours and 'm' minutes, accomodating all cases of singular, plural, and 0.
 
Takes an integer number of minutes and converts it into a string. The returned string has the form 'd' days, 'h' hours and 'm' minutes, accomodating all cases of singular, plural, and 0.
+
 
 
'''Parameters:'''
 
'''Parameters:'''
 
:;minutes:Number. The time in minutes.
 
:;minutes:Number. The time in minutes.
+
 
 
'''Returns:'''
 
'''Returns:'''
 
:;timeString:String.
 
:;timeString:String.
{{CodeEx|codeex=var str = this.myHelper.strDateFromMinutes(56566);
+
 
str -> 39 days, 6 hours and 46 minutes<br>
+
  var str = this.myHelper.strDateFromMinutes(56566);
var str = this.myHelper.strDateFromMinutes(-56566);<br>
+
  str -> 39 days, 6 hours and 46 minutes
str -> 39 days, 6 hours and 46 minutes ago}}
+
  var str = this.myHelper.strDateFromMinutes(-56566);
 +
  str -> 39 days, 6 hours and 46 minutes ago
  
 
Author: Commander McLane.
 
Author: Commander McLane.
Line 287: Line 315:
 
:;dec_str:String/Boolean.  Decrypted string or false.
 
:;dec_str:String/Boolean.  Decrypted string or false.
  
{{CodeEx|codeex=var test = this.myHelper.strDecrypt("6053cae17efb01230f4768046cac63","MYPASS");
+
  var test = this.myHelper.strDecrypt("6053cae17efb01230f4768046cac63","MYPASS");
test -> "Hello world"}}
+
  test -> "Hello world"
  
 
Author: Terry Yuen.
 
Author: Terry Yuen.
Line 305: Line 333:
 
:;enc_str:String/Boolean.  Encrypted string or false.
 
:;enc_str:String/Boolean.  Encrypted string or false.
  
{{CodeEx|codeex=var test = this.myHelper.strEncrypt("Hello world","MYPASS");
+
  var test = this.myHelper.strEncrypt("Hello world","MYPASS");
test -> "6053cae17efb01230f4768046cac63"}}
+
  test -> "6053cae17efb01230f4768046cac63"
  
 
Author: Terry Yuen.
 
Author: Terry Yuen.
Line 322: Line 350:
 
:;crc:Number.  The CRC.
 
:;crc:Number.  The CRC.
  
{{CodeEx|codeex=var crc = this.myHelper.strGetCRC("Hello");
+
  var crc = this.myHelper.strGetCRC("Hello");
crc -> 500}}
+
  crc -> 500
  
  
Line 337: Line 365:
 
:;str:String.  With leading zero if necessary.
 
:;str:String.  With leading zero if necessary.
  
{{CodeEx|codeex=var a = this.myHelper.strLZ(3);
+
  var a = this.myHelper.strLZ(3);
a -> "03"}}
+
  a -> "03"
  
 
Author: Dr.J R Stockton.
 
Author: Dr.J R Stockton.
Line 354: Line 382:
 
:;str:String.  With leading zeros if necessary.
 
:;str:String.  With leading zeros if necessary.
  
{{CodeEx|codeex=var a = this.myHelper.strLZZ(3);
+
  var a = this.myHelper.strLZZ(3);
a -> "003"}}
+
  a -> "003"
  
 
Author: Dr.J R Stockton.
 
Author: Dr.J R Stockton.
Line 372: Line 400:
 
:;str:String. Filled up with leading zeros.
 
:;str:String. Filled up with leading zeros.
  
{{CodeEx|codeex=var a = this.myHelper.strNLZ(3,4);
+
  var a = this.myHelper.strNLZ(3,4);
a -> "0003"}}
+
  a -> "0003"
  
  
 
=== strRandom() ===
 
=== strRandom() ===
{{CodeEx|codeex=strRandom: function( l )}}
+
{{CodeEx|codeex=strRandom: function( le )}}
{{CodeExTime|native=0.000057|extension=0.000012|js=0.000171}}
+
{{CodeExTime|native=0.000041|extension=0.000013|js=0.000094}}
Returns random string with length of l.
+
Returns random string with length of le.
  
 
'''Parameters:'''
 
'''Parameters:'''
:;l:Number. Length.
+
:;le:Number. Length.
 +
:;charSet:String. Optional. Used set of chars.
  
 
'''Returns:'''
 
'''Returns:'''
 
:;str:String with specified length.
 
:;str:String with specified length.
  
{{CodeEx|codeex=var a = this.myHelper.strRandom(6);
+
  var a = this.myHelper.strRandom(6);
a -> "hsdoiv"}}
+
  a -> "hsdoiv"
  
  
 
=== strRandomInt() ===
 
=== strRandomInt() ===
{{CodeEx|codeex=strRandomInt: function( l )}}
+
{{CodeEx|codeex=strRandomInt: function( le )}}
 
{{CodeExTime|native=0.000048|extension=0.000011|js=0.000070}}
 
{{CodeExTime|native=0.000048|extension=0.000011|js=0.000070}}
 
Returns random numbered string with length of l.
 
Returns random numbered string with length of l.
  
 
'''Parameters:'''
 
'''Parameters:'''
:;l:Number. Length in range of 1...9.
+
:;le:Number. Length in range of 1...9.
  
 
'''Returns:'''
 
'''Returns:'''
 
:;str:String with specified length.
 
:;str:String with specified length.
  
{{CodeEx|codeex=var a = this.myHelper.strRandomInt(6);
+
  var a = this.myHelper.strRandomInt(6);
a -> "524567"}}
+
  a -> "524567"
  
  
Line 418: Line 447:
 
:;out:String.  With specified length.
 
:;out:String.  With specified length.
  
{{CodeEx|codeex=var scr = this.myHelper.strScreenSubString("Iwantthisandnotthatandforsurenotsuch",16);
+
  var scr = this.myHelper.strScreenSubString("Iwantthisandnotthatandforsurenotsuch",16);
scr -> "Iwantthisandnott\nhatandforsurenot\nsuch"}}
+
  scr -> "Iwantthisandnott\nhatandforsurenot\nsuch"
  
  
Line 435: Line 464:
 
:;display:String.  With linebreaks.
 
:;display:String.  With linebreaks.
  
{{CodeEx|codeex=var scr = this.myHelper.strScreenString("I want this and not that and for sure not such",1,16);
+
  var scr = this.myHelper.strScreenString("I want this and not that and for sure not such",1,16);
scr -> "I want this and\nnot that and for\nsure not such"}}
+
  scr -> "I want this and\nnot that and for\nsure not such"
  
  
Line 451: Line 480:
 
:;out:Array.  Containing Strings with n words per element.
 
:;out:Array.  Containing Strings with n words per element.
  
{{CodeEx|codeex=var cleanedArray = this.myHelper.strSplitToPhrases("My cat has a good time",3);
+
  var cleanedArray = this.myHelper.strSplitToPhrases("My cat has a good time",3);
cleanedArray -> "My cat has","cat has a","has a good","a good time"}}
+
  cleanedArray -> ["My cat has","cat has a","has a good","a good time"]
  
  
 
=== strToWidth() ===
 
=== strToWidth() ===
 
{{CodeEx|codeex=strToWidth: function( str, max, chr )}}
 
{{CodeEx|codeex=strToWidth: function( str, max, chr )}}
{{CodeExTime|native=0.000731|extension=0.000151|js=0.000164}}
+
{{CodeExTime|native=0.000086|extension=0.000040|js=0.000102}}
 
Returns string with specific length based on Oolites font size.  If stringwidth > max it is truncated, otherwise filled up with space or specified chr.
 
Returns string with specific length based on Oolites font size.  If stringwidth > max it is truncated, otherwise filled up with space or specified chr.
  
Line 468: Line 497:
 
:;str:String.  With specified width.
 
:;str:String.  With specified width.
  
{{CodeEx|codeex=var a = this.myHelper.strToWidth("MyveryOwnApproach",3);
+
  var a = this.myHelper.strToWidth("MyveryOwnApproach",3);
a -> "Myvery"}}
+
  a -> "Myvery"
  
  
 
=== strTrim() ===
 
=== strTrim() ===
 
{{CodeEx|codeex=strTrim: function( str )}}
 
{{CodeEx|codeex=strTrim: function( str )}}
{{CodeExTime|native=0.000049|extension=0.000011|js=0.000081}}
+
{{CodeExTime|native=0.000036|extension=0.000011|js=0.000080}}
Returns trimmed string.
+
Returns trimmed string. The difference to SpiderMonkeys native <tt>.trim()</tt> is that it removes not only leading or trailing whitespaces. It replaces also control characters (\b\f\r\n\t\v) via Regexp.
  
 
'''Parameters:'''
 
'''Parameters:'''
Line 483: Line 512:
 
:;str:String.
 
:;str:String.
  
{{CodeEx|codeex=var a = this.myHelper.strTrim(" Myvery ");
+
  var a = this.myHelper.strTrim(" Myvery ");
a -> "Myvery"}}
+
  a -> "Myvery"
 
 
Note: SpiderMonkey supports a native .trim().
 
  
  
Line 501: Line 528:
 
:;diff:Array.  Difference between two arrays.
 
:;diff:Array.  Difference between two arrays.
  
{{CodeEx|codeex=var testA = ["AA","AB","AC"],testB = ["AB","AC","AD"];
+
  var testA = ["AA","AB","AC"],testB = ["AB","AC","AD"];
var cleanedArray = this.myHelper.arrDiff(testA,testB);<br>
+
  var cleanedArray = this.myHelper.arrDiff(testA,testB);
cleanedArray -> "AA","AD"}}
+
  cleanedArray -> ["AA","AD"]
 +
 
 +
 
 +
=== arrFlat() ===
 +
{{CodeEx|codeex=arrFlat: function( arr ) {{AV|1.8}} }}
 +
{{CodeExTime|native=0.000039|extension=0.000012|js=0.000259}}
 +
Flattens multidimensional arrays.
 +
 
 +
'''Parameters:'''
 +
:;arr:Array. To be flattened.
 +
 
 +
'''Returns:'''
 +
:;r:Array.
 +
 
 +
  var a = [ ["AA"],["AB"],[ ["AC"] ] ];
 +
  var b = this.myHelper.arrFlat(a);
 +
  b -> ["AA","AB","AC"]
  
  
Line 509: Line 552:
 
{{CodeEx|codeex=arrRemoveByValue: function( arr, val )}}
 
{{CodeEx|codeex=arrRemoveByValue: function( arr, val )}}
 
{{CodeExTime|native=0.000038|extension=0.000010|js=0.000070}}
 
{{CodeExTime|native=0.000038|extension=0.000010|js=0.000070}}
Removes specific entry from array.
+
Removes specific entry from array. The method works in-place.
  
 
'''Parameters:'''
 
'''Parameters:'''
Line 518: Line 561:
 
:;arr:Array.  The cleaned array.
 
:;arr:Array.  The cleaned array.
  
{{CodeEx|codeex=var testA = ["A","B","C"];
+
  var testA = ["A","B","C"];
var cleanedArray = this.myHelper.arrRemoveByValue(testA,"B");<br>
+
  var cleanedArray = this.myHelper.arrRemoveByValue(testA,"B");
cleanedArray -> "A","C"}}
+
  cleanedArray -> ["A","C"]
  
  
 
=== arrShuffle() ===
 
=== arrShuffle() ===
 
{{CodeEx|codeex=arrShuffle: function( arr )}}
 
{{CodeEx|codeex=arrShuffle: function( arr )}}
{{CodeExTime|native=0.000036|extension=0.000010|js=0.000231}}
+
{{CodeExTime|native=0.000037|extension=0.000011|js=0.000191}}
 
Returns shuffled array.
 
Returns shuffled array.
  
Line 532: Line 575:
  
 
'''Returns:'''
 
'''Returns:'''
:;SHU:Array. Shuffled.
+
:;ar:Array. Shuffled.
{{CodeEx|codeex=var Q = "ABCDEFGHIKJKLM".split("");
+
 
var shuffledArray = this.myHelper.arrShuffle(Q);<br>
+
  var Q = "ABCDEFGHIKJKLM".split("");
shuffledArray -> ["B","I","M","A","K","C","F","H","K","J","D","E","L","G"]}}
+
  var shuffledArray = this.myHelper.arrShuffle(Q);
Author: Dr.J R Stockton.
+
  shuffledArray -> ["B","I","M","A","K","C","F","H","K","J","D","E","L","G"]
 +
 
 +
Author: Ronald Fisher and Frank Yates
  
  
 
=== arrSortByProperty() ===
 
=== arrSortByProperty() ===
 
{{CodeEx|codeex=arrSortByProperty: function( arr, prop )}}
 
{{CodeEx|codeex=arrSortByProperty: function( arr, prop )}}
{{CodeExTime|native=0.000035|extension=0.000011|js=0.000103}}
+
{{CodeExTime|native=0.000034|extension=0.000010|js=0.000088}}
Sort array containing objects by specific property.
+
Sort array containing objects by specific property. Starting with v1.7.1 it uses a SelectionSort algorithm. The method works in-place.
  
 
'''Parameters:'''
 
'''Parameters:'''
Line 551: Line 596:
 
:;what:Array.  Sorted by specified property.
 
:;what:Array.  Sorted by specified property.
  
{{CodeEx|codeex=var objA = [{ID:2,Other:"TestA"},{ID:1,Other:"TestB"}];
+
  var objA = [{ID:2,Other:"TestA"},{ID:1,Other:"TestB"}];
var sorted = this.myHelper.arrSortByProperty(objA,"ID");<br>
+
  var sorted = this.myHelper.arrSortByProperty(objA,"ID");
sorted -> [{ID:1,Other:"TestB"},{ID:2,Other:"TestA"}]}}
+
  sorted -> [{ID:1,Other:"TestB"},{ID:2,Other:"TestA"}]
 +
 
 +
Author: Nicholas C. Zakas.
  
  
Line 567: Line 614:
 
:;r:Array.  The cleaned array.
 
:;r:Array.  The cleaned array.
  
{{CodeEx|codeex=var testArray = ["AB","AB","AB","AC","AC","AC"];
+
  var testArray = ["AB","AB","AB","AC","AC","AC"];
var cleanedArray = this.myHelper.arrUnique(testArray);<br>
+
  var cleanedArray = this.myHelper.arrUnique(testArray);
cleanedArray -> "AB","AC"}}
+
  cleanedArray -> ["AB","AC"]
 +
 
 +
 
 +
=== objClone() ===
 +
{{CodeEx|codeex=objClone: function( src ) {{AV|1.8}} }}
 +
{{CodeExTime|native=0.000033|extension=0.000009|js=0.000146}}
 +
Creates a clone of the input object.
 +
 
 +
'''Parameters:'''
 +
:;src:Object. To be copied.
 +
 
 +
'''Returns:'''
 +
:;obj:Object. Cloned object.
 +
 
 +
  var dir = this.myHelper.objClone({a:["a","b"],b:["c","d"]});
 +
 
 +
 
 +
=== objFindKeyValue() ===
 +
{{CodeEx|codeex=objFindKeyValue: function( obj, key, value ) {{AV|1.8}} }}
 +
{{CodeExTime|native=0.000040|extension=0.000011|js=0.000139}}
 +
Returns all objects which match key===value.
 +
 
 +
'''Parameters:'''
 +
:;obj:Object. To be checked.
 +
:;key:String. Keyname.
 +
:;value:Any.
 +
 
 +
'''Returns:'''
 +
:;result:Array. All objects where key===value.
 +
 
 +
  var x = {a:[{id:2},{id:4}],b:["c","d"]};
 +
  var y= this.myHelper.objClone(x,"id",4);
 +
  -> {id:4}
  
  
Line 583: Line 662:
 
'''Returns:'''
 
'''Returns:'''
 
:;str:String.
 
:;str:String.
{{CodeEx|codeex=var dir = this.myHelper.mapCoordsDirection([27,33,0]);
+
 
dir -> "north-west"}}
+
  var dir = this.myHelper.mapCoordsDirection([27,33,0]);
 +
  dir -> "north-west"
  
 
Author: Eric Walch.
 
Author: Eric Walch.
Line 591: Line 671:
 
=== oxpVersionTest() ===
 
=== oxpVersionTest() ===
 
{{CodeEx|codeex=oxpVersionTest: function( who, requires, quiet )}}
 
{{CodeEx|codeex=oxpVersionTest: function( who, requires, quiet )}}
{{CodeExTime|native=0.000345|extension=0.000060|js=0.000223}}
+
{{CodeExTime|native=0.000456|extension=0.000061|js=0.000201}}
 
Checks required OXPs and versions. The array is expected to contain two elements for each script and version must be null for legacy scripts!
 
Checks required OXPs and versions. The array is expected to contain two elements for each script and version must be null for legacy scripts!
  
Line 607: Line 687:
 
* true - Otherwise.
 
* true - Otherwise.
  
{{CodeEx|codeex=var requires = ["snoopers","2.0.8","vector","1.5","Cabal_Common_Keyboard","1.0"];
+
  var requires = ["snoopers","2.0.8","vector","1.5","Cabal_Common_Keyboard","1.0"];
var checked = this.myHelper.oxpVersionTest(this.name,requires);<br>
+
  var checked = this.myHelper.oxpVersionTest(this.name,requires);
checked -> true (or false)}}
+
  checked -> true (or false)
  
  
 
=== oxpVersionTest2Array() ===
 
=== oxpVersionTest2Array() ===
 
{{CodeEx|codeex=oxpVersionTest2Array: function( who, requires, quiet )}}
 
{{CodeEx|codeex=oxpVersionTest2Array: function( who, requires, quiet )}}
{{CodeExTime|native=0.000344|extension=0.000066|js=0.000215}}
+
{{CodeExTime|native=0.000299|extension=0.000061|js=0.000198}}
 
Checks required OXPs and versions. The array is expected to contain two elements for each script and version must be null for legacy scripts! See the description for oxpVersionTest() for more details.
 
Checks required OXPs and versions. The array is expected to contain two elements for each script and version must be null for legacy scripts! See the description for oxpVersionTest() for more details.
  
Line 630: Line 710:
 
* -2 - version is lower.
 
* -2 - version is lower.
  
{{CodeEx|codeex=var requires = ["snoopers","2.0.8","vector","1.5","Cabal_Common_Keyboard","1.0"];
+
  var requires = ["snoopers","2.0.8","vector","1.5","Cabal_Common_Keyboard","1.0"];
var checked = this.myHelper.oxpVersionTest2Array(this.name,requires);<br>
+
  var checked = this.myHelper.oxpVersionTest2Array(this.name,requires);
checked -> 1,-2,1}}
+
  checked -> [1,-2,1]
  
  
Line 653: Line 733:
 
:;mv:Entity.  Returns modelview Entity or null.
 
:;mv:Entity.  Returns modelview Entity or null.
  
{{CodeEx|codeex=var a = this.myHelper.entModelView();
+
  var a = this.myHelper.entModelView();
a -> [Ship "cabal_common_modelview" position: (8846.43, 8857.51, -2544.76) scanClass: CLASS_NEUTRAL status: STATUS_IN_FLIGHT]}}
+
  a -> [Ship "cabal_common_modelview" position: (8846.43, 8857.51, -2544.76) scanClass: CLASS_NEUTRAL status: STATUS_IN_FLIGHT]
  
  
Line 669: Line 749:
 
:;nothing.
 
:;nothing.
  
{{CodeEx|codeex=var a = player.ship.target;
+
  var a = player.ship.target;
var b = system.mainPlanet;<br>
+
  var b = system.mainPlanet;
this.myHelper.entFaceEntity(a,b);}}
+
  this.myHelper.entFaceEntity(a,b);
  
  
Line 688: Line 768:
 
nothing.
 
nothing.
  
{{CodeEx|codeex=this.myHelper.entScreenCornerPos(0.8,0.9,1.1,3.2);}}
+
  var scr = this.myHelper.entScreenCornerPos(0.8,0.9,1.1,3.2);
  
  
Line 703: Line 783:
 
:;n:Number.
 
:;n:Number.
  
{{CodeEx|codeex=var a = this.myHelper.screenGCD(25,5);
+
  var a = this.myHelper.screenGCD(25,5);
a -> 5}}
+
  a -> 5
  
  
Line 719: Line 799:
 
:;n:Number.
 
:;n:Number.
  
{{CodeEx|codeex=var a = this.myHelper.screenAspect(1024,768);
+
  var a = this.myHelper.screenAspect(1024,768);
a -> 1.3333333333}}
+
  a -> 1.3333333333
  
  
Line 735: Line 815:
 
:;a:Array.
 
:;a:Array.
  
{{CodeEx|codeex=var a = this.myHelper.screenChecks();
+
  var a = this.myHelper.screenChecks();
a -> [1024,768,256,1.33333333]}}
+
  a -> [1024,768,256,1.33333333]
 +
 
 +
 
 +
== Methods ==
 +
=== findSystemsPredicate() ===
 +
{{CodeEx|codeex=findSystemsPredicate( arr ) {{AV|1.8}} }}
 +
{{CodeExTime|native=0.000043|extension=0.000011|js=0.001751}}
 +
Returns array with <tt>system.IDs</tt> if the system data matches the passed conditions. The method uses the binary searchtree in [[#galaxyStats|galaxyStats]], so it is available after <tt>startUp</tt> only.
 +
 
 +
'''Parameters:'''
 +
:;arr:Array. Holds objects with the following members to compare system data against.
 +
:::Object:
 +
::::eco:Number. In range [0...7].
 +
::::gov:Number. In range [0...7].
 +
::::tec:Number. In range [0...15].
 +
:::::All members above need also:
 +
::::c:Number. Required. In range [1...4] with 1=Equal, 2=Not equal, 3=Greaterthan, 4=Lessthan.
 +
 
 +
'''Returns:'''
 +
:;result:Array. Either empty or holding <tt>system.IDs</tt>.
 +
 
 +
  var a = [{eco:0,c:1},{gov:7,c:1},{tec:12,c:3}];
 +
  var b = worldScripts.Cabal_Common_Functions.findSystemsPredicate(a);
 +
 
 +
 
 +
=== updateGalaxyStats() ===
 +
{{CodeEx|codeex=updateGalaxyStats( id ) {{AV|1.8}} }}
 +
Updates nodes in [[#galaxyStats|galaxyStats]] and lists [[#ecos|ecos]], [[#govs|govs]], [[#tecs|tecs]] and [[#nova|nova]]. If id is not specified current <tt>system.ID</tt> is used if player is not in interstellar space.
 +
 
 +
'''Parameters:'''
 +
:;id:Number. Optional <tt>system.ID</tt>.
 +
 
 +
'''Returns:'''
 +
:;nothing.
  
  
Line 742: Line 855:
 
=== moreInfo ===
 
=== moreInfo ===
 
Holds additional infos which can be useful for OXPs. The object holds several properties and methods. Scripts can gather the infos
 
Holds additional infos which can be useful for OXPs. The object holds several properties and methods. Scripts can gather the infos
{{CodeEx|codeex=var myInfo = worldScripts.Cabal_Common_Functions.moreInfo;}}
+
  var myInfo = worldScripts.Cabal_Common_Functions.moreInfo;
  
 
==== moreInfo Properties ====
 
==== moreInfo Properties ====
 
:;avgEnts:Number. Average number of entities on <code>shipExitedWitchspace</code> in the first 30 jumps in a session.
 
:;avgEnts:Number. Average number of entities on <code>shipExitedWitchspace</code> in the first 30 jumps in a session.
 
:;avgEntsOXP:Number. Delayed average number of entities (30 jumps).
 
:;avgEntsOXP:Number. Delayed average number of entities (30 jumps).
:;connected:Array. Delayed as it is timeintensive. Holds system.IDs of connected systems from the current location. The path finding is executed after <code>startUp</code> and <code>playerEnteredNewGalaxy</code> only. (New in v1.6.1)
 
 
:;jumpCount:Number of jumps the player has done in this session.
 
:;jumpCount:Number of jumps the player has done in this session.
 +
:;lastJumpDiff:Number. Time difference between <code>lastJumpTime</code> and current time.
 
:;lastJumpTime:Number. Time when the last jump occured. Uses <code>clock.absoluteSeconds</code>
 
:;lastJumpTime:Number. Time when the last jump occured. Uses <code>clock.absoluteSeconds</code>
:;lastJumpDiff:Number. Time difference between <code>lastJumpTime</code> and current time.
+
 
 +
==== moreInfo Objects ====
 
<!--:;conEnt:Array. Holds the numbers of 30 jumps on <code>shipExitedWitchspace</code>.
 
<!--:;conEnt:Array. Holds the numbers of 30 jumps on <code>shipExitedWitchspace</code>.
 +
:;connected:{{AV|1.7}} Array. Delayed as it is timeintensive. Holds system.IDs of connected systems from the current location. The path finding is executed after <code>startUp</code> and <code>playerEnteredNewGalaxy</code> only.
 
:;conEntsOXP:Array. Delayed array holding the numbers of 30 jumps.-->
 
:;conEntsOXP:Array. Delayed array holding the numbers of 30 jumps.-->
 +
:;ecos:{{AV|1.8}} Array. Holds 8 arrays of system.IDs for the systems economy.
 +
:;govs:{{AV|1.8}} Array. Holds 8 arrays of system.IDs for the systems governments.
 +
:;tecs:{{AV|1.8}} Array. Holds 16 arrays of system.IDs for the systems techlevels. If the systems techlevel is >14, it is stored in tecs[15].
  
==== moreInfo Objects ====
+
{{CodeExTime|native=0.000050|extension=0.000016|js=0.000087}}
:;galaxyStats:Object. Binary search tree. The collected objects are holding only primitive values (= no references to System.infoForSystem) to keep it fast.
+
:;galaxyStats:{{AV|1.7}} Object. Binary search tree. The collected objects are holding only primitive values (= no references to System.infoForSystem) to keep it fast. <tt>coordinates, description, economy, government, ID, inhabitant, inhabitants, market, name, population, productivity, radius, sun</tt> (true, if sun_gone_nova false) and <tt>techlevel</tt> are stored.
 
 
::coordinates, description, economy, government, ID, inhabitant, inhabitants, market, name, population, productivity, radius, sun (true, if sun_gone_nova false) and techlevel are stored.
 
  
 
::Scripts can access the data via
 
::Scripts can access the data via
{{CodeEx|codeex=var myInfo = worldScripts.Cabal_Common_Functions.moreInfo.galaxyStats.contains(7).description;}}
+
  var myInfo = worldScripts.Cabal_Common_Functions.moreInfo.galaxyStats.contains(7);
{{CodeExTime|native=0.000050|extension=0.000016|js=0.000087}}
 
  
 
::The returned object holds the above mentioned properties for the requested system.
 
::The returned object holds the above mentioned properties for the requested system.

Revision as of 18:44, 24 September 2013

Overview

This is the main class for the helper library with its members and part of the Cabal_Common_Library.

Scripts can instantiate a copy of the API, e.g.

 this.myHelper = new worldScripts.Cabal_Common_Functions.Cabal_Common();

Versions before v1.6 have used this.myHelper = new Cabal_Common();


Added in v1.8

A convenience instance is created and can be used directly. This is specially useful if you only need a small part of the library.

 worldScripts.Cabal_Common_Functions.helper.getType(obj);

The Profiler boxes will give you a quick overview about runtimes. Times are measured with the listed examples on a Core2Duo @2GHz.


Properties

internalVersion

Number. Property to give OXPs a chance to check the required lib min. version easily. This number will be raised with every release.

 var a = worldScripts.Cabal_Common_Functions.internalVersion;

The property is available in the API as well.

 var a = this.myHelper.internalVersion;

Current version is

15


API Methods

baseChange()

baseChange: function( n, to, from )
Profiler
Native 0.000038s
Extension 0.000012s
JS 0.000067s

Changes the base of n.

Parameters:

n
Number. To be changed.
to
Number. Base which should be used to convert to. Usually 2,10 or 16.
from
Number. Optional. Base from which should be converted. Usually 2,10 or 16.

Returns:

str
String. Base changed.
 var a = this.myHelper.baseChange(10, 16); // convert decimal 10 to hex
 var b = this.myHelper.baseChange(0xA, 2); // convert hex 0xA (10) to binary
 var c = this.myHelper.baseChange('a', 2, 16); // alternative convert hex 0xA to binary
 a -> 'a', b -> '1010', c -> '1010'

Author: Dr.J R Stockton.


clamp()

clamp: function( value, max, min )
Profiler
Native 0.000041s
Extension 0.000012s
JS 0.000069s

Clamps value to max...min.

Paramaters:

value
Number. To be clamped.
max
Number. Maximum.
min
Number. Minimum.

Returns:

n
Number. Clamped.
 var a = this.myHelper.clamp(Math.random(),0.6,0.2);
 a -> 0.2


getType()

getType: function( what ) Added in v1.8
Profiler
Native 0.000040s
Extension 0.000010s
JS 0.000062s

Returns lowercase string with the type or null.

Parameters:

what
Object. To be evaluated.

Returns:

type
String or null. If String 'array', 'boolean', 'date', 'function', 'number', 'object', 'regexp', 'string', or 'undefined'
 var a = this.myHelper.getType("A");
 a -> "string"


msbPos()

msbPos: function( n )
Profiler
Native 0.000038s
Extension 0.000011s
JS 0.000063s

Returns position of most significant bit of n.

Paramaters:

n
Number. To be evaluated.

Returns:

n
Number. The position of the most significant bit or 0 (zero).
 var a = this.myHelper.msbPos(25);
 a -> 5

Author: Dr.J R Stockton.


nBitsUsed()

nBitsUsed: function( n )
Profiler
Native 0.000038s
Extension 0.000010s
JS 0.000062s

Returns number of bits set in n. If n<0 a bitwise NOT will be applied before execution.

Parameters:

n
Number. To be evaluated.

Returns:

e
Number. The counted number of bits set to 1.
 var a = this.myHelper.nBitsUsed(13);
 a -> 3


num2Prec()

num2Prec: function( x, p )
Profiler
Native 0.000041s
Extension 0.000010s
JS 0.000069s

Returns rounded number with specified precision.

Parameters:

x
Number. To be rounded.
p
Number. Precision.

Returns:

e
Number. The rounded number.
 var a = this.myHelper.num2Prec(25.06532123,3);
 a -> 25.065


pseudoRand()

pseudoRand: function( salt, mode )
Profiler
Native 0.000041s
Extension 0.000017s
JS 0.000106s

LCG (Linear congruential generator) pseudo-random number generator with salt (and pepper). Can be used to generate deterministic unique values, e.g. to decide if a specific entity should be spawned.

Parameters:

salt
Number. This is used to generate a pseudo random number.
mode
Boolean. Optional. If specified and true the returned value is integer (Math.floor(n*100)).

Returns:

n
Number.
  • No mode. In range 0...1,
  • mode. In range 0...100.
 var test = this.myHelper.pseudoRand(55);
 test -> 0.11969016003422439
 var test = this.myHelper.pseudoRand(55,true);
 test -> 11

Author: Jens Ayrton (Ahruman).


rand()

rand: function( n )
Profiler
Native 0.000038s
Extension 0.000011s
JS 0.000066s

Random number in range 0...n.

Parameters:

n
Number. Maximum value.

Returns:

n
Number. Returns the random Number.
 var crc = this.myHelper.rand(35);
 crc -> 12

Author: Dr.J R Stockton.


randSpan()

randSpan: function( minN, maxN )
Profiler
Native 0.000037s
Extension 0.000012s
JS 0.000086s

Random number in range minN...maxN.

Paramaters:

minN
Number. Minimum.
maxN
Number. Maximum.

Returns:

n
Number. The newly generated random Number.
 var crc = this.myHelper.randSpan(35,88);
 crc -> 55

Author: Dr.J R Stockton.


strAddAlignedText()

strAddAlignedText: function( text, alignment ) Added in v1.6.1
Profiler
Native 0.000122s
Extension 0.000028s
JS 0.000082s

Returns padded text for a single line.

Parameters:

text
String.
alignment
String. Optional. Either L, C or R. Default L.

Returns:

str
String. Padded text.

Author: Thargoid.


strAddEdgeText()

strAddEdgeText: function( leftText, rightText ) Added in v1.6.1
Profiler
Native 0.000159s
Extension 0.000040s
JS 0.000295s

Returns two edge-aligned columns, one on the left and the other on the right for a single line.

Parameters:

leftText
String.
rightText
String.

Returns:

str
String. Aligned text.

Author: Thargoid.


strAddIndentedText()

strAddIndentedText: function( text, indent ) Added in v1.6.1
Profiler
Native 0.000112s
Extension 0.000028s
JS 0.000133s

Returns indented line of text by the given distance (in ems) from the left.

Parameters:

text
String.
indent
Number. Value in ems.

Returns:

str
String. Indented text.

Author: Thargoid.


strAdd2Columns()

strAdd2Columns: function( leftText, leftIndent, rightText, rightIndent ) Added in v1.6.1
Profiler
Native 0.000137s
Extension 0.000057s
JS 0.000414s

Returns single line text with two columns indented from the left margin by the given amount (in ems, 0-32).

Parameters:

leftText
String.
leftIndent
Number. Valöue in ems.
rightText
String.
rightIndent
Number. Value in ems.

Returns:

str
String. Text with 2 columns.

Author: Thargoid.


strAdd3Columns()

strAdd3Columns: function( leftText, leftIndent, centreText, centreIndent, rightText, rightIndent ) Added in v1.6.1
Profiler
Native 0.000041s
Extension 0.000013s
JS 0.000366s

Returns single line text with three columns, left, centre and right.

Parameters:

leftText
String.
leftIndent
Number. Value in ems.
centreText
String.
centreIndent
Number. Value in ems.
rightText
String.
rightIndent
Number. Value in ems.

Returns:

str
String. Text with 3 columns.

Author: Thargoid.


strCompareVersion()

strCompareVersion: function( strA, strB )
Profiler
Native 0.000033s
Extension 0.000010s
JS 0.000080s

Compares version strings (like “2.0.3”) against each other and returns number. It also strips pre/suffixes like “Build” or “Beta”. Subroutine from oxpVersionTest() and oxpVersionTest2Array(), but can also be used directly.

Parameters:

strA
String. Actual version.
strB
String. Version to be compared against.

Returns:

  • 0 - Number. If strA < strB
  • 1 - Number. If strA = strB
  • 2 - Number. If strA > strB
 var check =  this.myHelper.strCompareVersion("Beta2.1","1.0.7");
 check -> 2


strDateFromMinutes()

strDateFromMinutes: function( minutes )
Profiler
Native 0.000038s
Extension 0.000011s
JS 0.000067s

Takes an integer number of minutes and converts it into a string. The returned string has the form 'd' days, 'h' hours and 'm' minutes, accomodating all cases of singular, plural, and 0.

Parameters:

minutes
Number. The time in minutes.

Returns:

timeString
String.
 var str = this.myHelper.strDateFromMinutes(56566);
 str -> 39 days, 6 hours and 46 minutes
 var str = this.myHelper.strDateFromMinutes(-56566);
 str -> 39 days, 6 hours and 46 minutes ago

Author: Commander McLane.


strDecrypt()

strDecrypt: function( str, pwd )
Profiler
Native 0.000038s
Extension 0.000012s
JS 0.000148s

Decrypts string.

Parameters:

str
String. To be decrypted. Minimum length 6 chars.
pwd
String. Password. Minimum length 4 chars.

Returns:

dec_str
String/Boolean. Decrypted string or false.
 var test = this.myHelper.strDecrypt("6053cae17efb01230f4768046cac63","MYPASS");
 test -> "Hello world"

Author: Terry Yuen.


strEncrypt()

strEncrypt: function( str, pwd )
Profiler
Native 0.000038s
Extension 0.000011s
JS 0.000137s

Encrypts string.

Parameters:

str
String. To be encrypted. Minimum length 6 chars.
pwd
String. Password. Minimum length 4 chars.

Returns:

enc_str
String/Boolean. Encrypted string or false.
 var test = this.myHelper.strEncrypt("Hello world","MYPASS");
 test -> "6053cae17efb01230f4768046cac63"

Author: Terry Yuen.


strGetCRC()

strGetCRC: function( str )
Profiler
Native 0.000038s
Extension 0.000011s
JS 0.000062s

Very simple CRC from string and does not create unique checksums. It uses Unicodes, but limits every char via &0xff and the output via &0x3fff.

Parameters:

str
String. Which should be used to create a CRC.

Returns:

crc
Number. The CRC.
 var crc = this.myHelper.strGetCRC("Hello");
 crc -> 500


strLZ()

strLZ: function( n )
Profiler
Native 0.000039s
Extension 0.000011s
JS 0.000060s

Returns string with a leading zero if n<10.

Parameters:

n
Number. To be evaluated.

Returns:

str
String. With leading zero if necessary.
 var a = this.myHelper.strLZ(3);
 a -> "03"

Author: Dr.J R Stockton.


strLZZ()

strLZZ: function( n )
Profiler
Native 0.000039s
Extension 0.000010s
JS 0.000095s

Returns string with a leading zeros if n<100. Uses strLZ() as subfunction.

Parameters:

n
Number. To be evaluated.

Returns:

str
String. With leading zeros if necessary.
 var a = this.myHelper.strLZZ(3);
 a -> "003"

Author: Dr.J R Stockton.


strNLZ()

strNLZ: function( n,len )
Profiler
Native 0.000039s
Extension 0.000011s
JS 0.000068s

Returns string with length of len filled with leading zeros.

Parameters:

n
Number. To be evaluated.
len
Number. Length. Maximum is 10.

Returns:

str
String. Filled up with leading zeros.
 var a = this.myHelper.strNLZ(3,4);
 a -> "0003"


strRandom()

strRandom: function( le )
Profiler
Native 0.000041s
Extension 0.000013s
JS 0.000094s

Returns random string with length of le.

Parameters:

le
Number. Length.
charSet
String. Optional. Used set of chars.

Returns:

str
String with specified length.
 var a = this.myHelper.strRandom(6);
 a -> "hsdoiv"


strRandomInt()

strRandomInt: function( le )
Profiler
Native 0.000048s
Extension 0.000011s
JS 0.000070s

Returns random numbered string with length of l.

Parameters:

le
Number. Length in range of 1...9.

Returns:

str
String with specified length.
 var a = this.myHelper.strRandomInt(6);
 a -> "524567"


strScreenSubString()

strScreenSubString: function( str, chrs )
Profiler
Native 0.000038s
Extension 0.000010s
JS 0.000067s

Formats the string str into lines of at most chrs characters in length. Subfunction of strScreenString().

Parameters:

str
String. To be used.
chrs
Number. The length.

Returns:

out
String. With specified length.
 var scr = this.myHelper.strScreenSubString("Iwantthisandnotthatandforsurenotsuch",16);
 scr -> "Iwantthisandnott\nhatandforsurenot\nsuch"


strScreenString()

strScreenString: function( str, mode, chrs )
Profiler
Native 0.000038s
Extension 0.000011s
JS 0.000076s

Splits string in pieces of chrs, with intermediate linebreaks for missionscreens. The method splits the incoming string by spaces and loops over the elements, and tries to fill up the current line until the maximum length (chrs) is reached. If there are still remaining elements the next line will be used. The replacement (mode) is done via regexp and removes the following: ‘\t \r \f \n \v’. If splitting is not possible or a word is longer than chrs, strScreenSubString() will be used.

Parameters:

str
String. To be used.
mode
Boolean. Optional. If mode is false or not specified it replaces special signs like linebreaks with spaces.
chrs
Number. Optional. Length. If not specified default of 70 is used.

Returns:

display
String. With linebreaks.
 var scr = this.myHelper.strScreenString("I want this and not that and for sure not such",1,16);
 scr -> "I want this and\nnot that and for\nsure not such"


strSplitToPhrases()

strSplitToPhrases: function( str, n )
Profiler
Native 0.000038s
Extension 0.000010s
JS 0.000097s

Splits string into n words phrases.

Parameters:

str
String. To be used.
n
Number. Words.

Returns:

out
Array. Containing Strings with n words per element.
 var cleanedArray = this.myHelper.strSplitToPhrases("My cat has a good time",3);
 cleanedArray -> ["My cat has","cat has a","has a good","a good time"]


strToWidth()

strToWidth: function( str, max, chr )
Profiler
Native 0.000086s
Extension 0.000040s
JS 0.000102s

Returns string with specific length based on Oolites font size. If stringwidth > max it is truncated, otherwise filled up with space or specified chr.

Parameters:

str
String. To be used.
max
Number. Maximum width.
chr
String. Char to be used to fill up if stringwidth < max.

Returns:

str
String. With specified width.
 var a = this.myHelper.strToWidth("MyveryOwnApproach",3);
 a -> "Myvery"


strTrim()

strTrim: function( str )
Profiler
Native 0.000036s
Extension 0.000011s
JS 0.000080s

Returns trimmed string. The difference to SpiderMonkeys native .trim() is that it removes not only leading or trailing whitespaces. It replaces also control characters (\b\f\r\n\t\v) via Regexp.

Parameters:

str
String.

Returns:

str
String.
 var a = this.myHelper.strTrim(" Myvery ");
 a -> "Myvery"


arrDiff()

arrDiff: function( ar1, ar2 )
Profiler
Native 0.000038s
Extension 0.000012s
JS 0.000096s

Returns difference between two arrays.

Parameters:

ar1
Array. First.
ar2
Array. Second.

Returns:

diff
Array. Difference between two arrays.
 var testA = ["AA","AB","AC"],testB = ["AB","AC","AD"];
 var cleanedArray = this.myHelper.arrDiff(testA,testB);
 cleanedArray -> ["AA","AD"]


arrFlat()

arrFlat: function( arr ) Added in v1.8
Profiler
Native 0.000039s
Extension 0.000012s
JS 0.000259s

Flattens multidimensional arrays.

Parameters:

arr
Array. To be flattened.

Returns:

r
Array.
 var a = [ ["AA"],["AB"],[ ["AC"] ] ];
 var b = this.myHelper.arrFlat(a);
 b -> ["AA","AB","AC"]


arrRemoveByValue()

arrRemoveByValue: function( arr, val )
Profiler
Native 0.000038s
Extension 0.000010s
JS 0.000070s

Removes specific entry from array. The method works in-place.

Parameters:

arr
Array. From which things should be removed.
val
Object. Value that has to be removed.

Returns:

arr
Array. The cleaned array.
 var testA = ["A","B","C"];
 var cleanedArray = this.myHelper.arrRemoveByValue(testA,"B");
 cleanedArray -> ["A","C"]


arrShuffle()

arrShuffle: function( arr )
Profiler
Native 0.000037s
Extension 0.000011s
JS 0.000191s

Returns shuffled array.

Parameters:

arr
Array.

Returns:

ar
Array. Shuffled.
 var Q = "ABCDEFGHIKJKLM".split("");
 var shuffledArray = this.myHelper.arrShuffle(Q);
 shuffledArray -> ["B","I","M","A","K","C","F","H","K","J","D","E","L","G"]

Author: Ronald Fisher and Frank Yates


arrSortByProperty()

arrSortByProperty: function( arr, prop )
Profiler
Native 0.000034s
Extension 0.000010s
JS 0.000088s

Sort array containing objects by specific property. Starting with v1.7.1 it uses a SelectionSort algorithm. The method works in-place.

Parameters:

arr
Array. To be sorted.
prop
String. Propertyname.

Returns:

what
Array. Sorted by specified property.
 var objA = [{ID:2,Other:"TestA"},{ID:1,Other:"TestB"}];
 var sorted = this.myHelper.arrSortByProperty(objA,"ID");
 sorted -> [{ID:1,Other:"TestB"},{ID:2,Other:"TestA"}]

Author: Nicholas C. Zakas.


arrUnique()

arrUnique: function( arr )
Profiler
Native 0.000037s
Extension 0.000012s
JS 0.000072s

Removes duplicates from array.

Parameters:

arr
Array. The input array, from which duplicates are to be removed.

Returns:

r
Array. The cleaned array.
 var testArray = ["AB","AB","AB","AC","AC","AC"];
 var cleanedArray = this.myHelper.arrUnique(testArray);
 cleanedArray -> ["AB","AC"]


objClone()

objClone: function( src ) Added in v1.8
Profiler
Native 0.000033s
Extension 0.000009s
JS 0.000146s

Creates a clone of the input object.

Parameters:

src
Object. To be copied.

Returns:

obj
Object. Cloned object.
 var dir = this.myHelper.objClone({a:["a","b"],b:["c","d"]});


objFindKeyValue()

objFindKeyValue: function( obj, key, value ) Added in v1.8
Profiler
Native 0.000040s
Extension 0.000011s
JS 0.000139s

Returns all objects which match key===value.

Parameters:

obj
Object. To be checked.
key
String. Keyname.
value
Any.

Returns:

result
Array. All objects where key===value.
 var x = {a:[{id:2},{id:4}],b:["c","d"]};
 var y= this.myHelper.objClone(x,"id",4);
 -> {id:4}


mapCoordsDirection()

mapCoordsDirection: function( posA, posB )
Profiler
Native 0.000355s
Extension 0.000259s
JS 0.000140s

Returns the general direction of the target coordinates compared to the current (or specified) system coordinates.

Parameters:

posA
Vector/ID. Map coordinates in LYs or simply a system.ID.
posB
Vector/ID. Optional. Map coordinates in LYs or simply a system.ID. Defaults to current system coordinates.

Returns:

str
String.
 var dir = this.myHelper.mapCoordsDirection([27,33,0]);
 dir -> "north-west"

Author: Eric Walch.


oxpVersionTest()

oxpVersionTest: function( who, requires, quiet )
Profiler
Native 0.000456s
Extension 0.000061s
JS 0.000201s

Checks required OXPs and versions. The array is expected to contain two elements for each script and version must be null for legacy scripts!

Checking requirements can be a pain as the version property often contains several numbers, such as Oolites own scripts (“1.74.2”), and checking for a minimum version is sometimes necessary. The method does exactly this and returns false if the requirments are not matched and logs where they are not fullfilled. It also strips pre/suffixes like “Build” or “Beta”. To use it you’ll need an array of required OXPs and their versions. This array can hold JS and Legacy worldScripts and the version can be set to null (required for Legacy), false or 0 (integer) to bypass the version test and only perform the check for existance. The method checks for a property ‘deactivated’ in OXPs to determine whether or not they are deactived.

Parameters:

who
String. Actual scriptname. It’s only used to log for which OXP the requirements are not fullfilled.
requires
Array. Holds for every required OXP the scriptname and version. To check only for existance set version to null.
quiet
Boolean. Optional. If true don't log, only check.

Returns:

Boolean.
  • false - If a requirement is not fullfilled or OXP is deactivated,
  • true - Otherwise.
 var requires = ["snoopers","2.0.8","vector","1.5","Cabal_Common_Keyboard","1.0"];
 var checked = this.myHelper.oxpVersionTest(this.name,requires);
 checked -> true (or false)


oxpVersionTest2Array()

oxpVersionTest2Array: function( who, requires, quiet )
Profiler
Native 0.000299s
Extension 0.000061s
JS 0.000198s

Checks required OXPs and versions. The array is expected to contain two elements for each script and version must be null for legacy scripts! See the description for oxpVersionTest() for more details.

Parameters:

who
String. Actual scriptname. It’s only used to log for which OXP the requirements are not fullfilled.
requires
Array. Holds for every required OXP the scriptname and version. To check only for existance set version to null.
quiet
Boolean. Optional. If true don't log, only check.

Returns:

checked
Array. With values for checked elements of requires.
  • 2 - version is greater,
  • 1 - version is equal,
  • 0 - not installed,
  • -1 - OXP is deactivated,
  • -2 - version is lower.
 var requires = ["snoopers","2.0.8","vector","1.5","Cabal_Common_Keyboard","1.0"];
 var checked = this.myHelper.oxpVersionTest2Array(this.name,requires);
 checked -> [1,-2,1]


entModelView()

entModelView: function( which )
Profiler
Native 0s
Extension 0s
JS 0s

Spawns or resets the modelview entity and returns it. Via JS we can set the orientation, position, etc. of the displayed model, but we can’t stop the rotation if spinModel is not explicitely set to false, because it is hardcoded for screen models and the AI of the model itself can’t do it, because AIs are not executed on missionscreens. That’s why we sometimes need a control entity to do the job.

The modelview entity scans for a specific role and if found sets its target and does the “safeScriptActionOnTarget: performTumble” on the missionscreen model. This overrides the hardcoded rotation with the specified settings in shipdata.plist for the model.

The model (for the missionscreen) has to declare

  • role to be scanned via modelview entity - default for the library is ‘cabal_common_model’.
  • max_flight_pitch (usually between 0..0.2)
  • max_flight_roll (usually between 0..0.2)

Parameters:

which
String. Optional. Role to be used for modelview. If not specified defaults to ‘cabal_common_modelview’.

Returns:

mv
Entity. Returns modelview Entity or null.
 var a = this.myHelper.entModelView();
 a -> [Ship "cabal_common_modelview" position: (8846.43, 8857.51, -2544.76) scanClass: CLASS_NEUTRAL status: STATUS_IN_FLIGHT]


entFaceEntity()

entFaceEntity: function( ent1, ent2 )
Profiler
Native 0.000408s
Extension 0.000193s
JS 0.000164s

This function causes ent1 to be reorientated such that it faces ent2. A common use-case is when spawning stations whose docking tunnel should face another entity, typically the main planet. Reorienting is instantly.

Parameters:

ent1
Entity. To be reoriented.
ent2
Entity. To which ent1 should be oriented.

Returns:

nothing.
 var a = player.ship.target;
 var b = system.mainPlanet;
 this.myHelper.entFaceEntity(a,b);


entScreenCornerPos()

entScreenCornerPos: function( level, signx, signy, further )
Profiler
Native 0.000811s
Extension 0.000335s
JS 0.000264s

Missionscreen model corner positioning.

Parameters:

level
Number. Amount of moving to screen corner. (0.0 ... 1.0).
signx
Number. Used as sign mantissa and multiplier (-1...1) for X axis.
signy
Number. Used as sign mantissa and multiplier (-1...1) for Y axis.
further
Number. Multiplier for Z axis. Defaults to 1.3.

Returns: nothing.

 var scr = this.myHelper.entScreenCornerPos(0.8,0.9,1.1,3.2);


screenGCD()

screenGCD: function( a, b )
Profiler
Native 0.000047s
Extension 0.000011s
JS 0.000095s

Returns greatest common denominator. Subfunction of .screenChecks().

Parameters:

a
Number.
b
Number.

Returns:

n
Number.
 var a = this.myHelper.screenGCD(25,5);
 a -> 5


screenAspect()

screenAspect: function( w, h )
Profiler
Native 0.000043s
Extension 0.000011s
JS 0.000117s

Returns aspect ratio. Subfunction of .screenChecks().

Parameters:

w
Number. Width.
h
Number. Height.

Returns:

n
Number.
 var a = this.myHelper.screenAspect(1024,768);
 a -> 1.3333333333


screenChecks()

screenChecks: function( w, h )
Profiler
Native 0.000348s
Extension 0.000104s
JS 0.000164s

Returns array with width, height, gcd and aspect ratio.

Parameters:

w
Number. Width. Optional.
h
Number. Height. Optional.

Returns:

a
Array.
 var a = this.myHelper.screenChecks();
 a -> [1024,768,256,1.33333333]


Methods

findSystemsPredicate()

findSystemsPredicate( arr ) Added in v1.8
Profiler
Native 0.000043s
Extension 0.000011s
JS 0.001751s

Returns array with system.IDs if the system data matches the passed conditions. The method uses the binary searchtree in galaxyStats, so it is available after startUp only.

Parameters:

arr
Array. Holds objects with the following members to compare system data against.
Object:
eco:Number. In range [0...7].
gov:Number. In range [0...7].
tec:Number. In range [0...15].
All members above need also:
c:Number. Required. In range [1...4] with 1=Equal, 2=Not equal, 3=Greaterthan, 4=Lessthan.

Returns:

result
Array. Either empty or holding system.IDs.
 var a = [{eco:0,c:1},{gov:7,c:1},{tec:12,c:3}];
 var b = worldScripts.Cabal_Common_Functions.findSystemsPredicate(a);


updateGalaxyStats()

updateGalaxyStats( id ) Added in v1.8

Updates nodes in galaxyStats and lists ecos, govs, tecs and nova. If id is not specified current system.ID is used if player is not in interstellar space.

Parameters:

id
Number. Optional system.ID.

Returns:

nothing.


Objects

moreInfo

Holds additional infos which can be useful for OXPs. The object holds several properties and methods. Scripts can gather the infos

 var myInfo = worldScripts.Cabal_Common_Functions.moreInfo;

moreInfo Properties

avgEnts
Number. Average number of entities on shipExitedWitchspace in the first 30 jumps in a session.
avgEntsOXP
Number. Delayed average number of entities (30 jumps).
jumpCount
Number of jumps the player has done in this session.
lastJumpDiff
Number. Time difference between lastJumpTime and current time.
lastJumpTime
Number. Time when the last jump occured. Uses clock.absoluteSeconds

moreInfo Objects

ecos
Added in v1.8 Array. Holds 8 arrays of system.IDs for the systems economy.
govs
Added in v1.8 Array. Holds 8 arrays of system.IDs for the systems governments.
tecs
Added in v1.8 Array. Holds 16 arrays of system.IDs for the systems techlevels. If the systems techlevel is >14, it is stored in tecs[15].


Profiler
Native 0.000050s
Extension 0.000016s
JS 0.000087s
galaxyStats
Added in v1.7 Object. Binary search tree. The collected objects are holding only primitive values (= no references to System.infoForSystem) to keep it fast. coordinates, description, economy, government, ID, inhabitant, inhabitants, market, name, population, productivity, radius, sun (true, if sun_gone_nova false) and techlevel are stored.
Scripts can access the data via
 var myInfo = worldScripts.Cabal_Common_Functions.moreInfo.galaxyStats.contains(7);
The returned object holds the above mentioned properties for the requested system.
Building the search tree is costly though, so the script does it only on startUp and playerEnteredNewGalaxy. Accessing all systems eats >200 ms, but getting values from this search tree is ~10 times faster for every access than getting it directly via System.infoForSystem, so it is suitable for OXPs which need to access multiple system data sets.
The nodes for the current system are updated on shipWillEnterWitchspace and shipWillExitWitchspace.