SMtonumber(string s)

Convert the leading numeric chars of a string to number.

Lua's tonumber can't convert "213abc" to number, it returns nil.
This function will return 123, ignoring the letters.
Note that it will break a scientific notation of a number "1.234e+56"

Return

number: or nil

Example

 print(tonumber("123abc")) --> 123
 print(tonumber("abc123")) --> nil
 print(tonumber("-.5x")) --> -0.5

CompareVersions(string a, string b)

Compare two version numbers in x.y.z string format.

Return

string: "<", ">" or "=" if a is lower, greater or equal to b.

Example

CompareVersions("9.9.7", "9.9.6") --> ">"

CompareMyrScriptVersion(string version)

Is MyrScript =, < or > version x.y.z?

As Application.MyrScriptVersion is a string, comparison may fail in the future, "10.1.1" is greater than "9.9.9" but string comparison will stay it's lower (because "1" < "9").

Return

string: "<", ">" or "=" if Application.MyrScriptVersion is lower, greater or equal to version.

round(number num, int numberOfDecimals)

Round a number.

Return

number: the rounded number, i.e. floor(number + 0.5) for an integer (no decimals)

NumberOfDecimals(number n)

Get the number of decimals of a number

Return

number: number

bound(number n, number mini, number maxi)

Ensure number n is within bounds [mini:maxi].

bound(n, mini, maxi) is a syntaxic sugar for max(min(n, maxi), mini)

Return

number: Bounded n.

dpi72_to_cm(number n, number zoom)

Convert a 72 DPI pixel value into centimeters.

Return

number: number

See

cm_to_dpi72

cm_to_dpi72(number n, number zoom)

Convert a centimeter value into 72 DPI pixels.

Return

number: number

See

dpi72_to_cm

SMPitchToString(int pitch, int preferredAccidental, int compatible, string preferredNote)

Extension and bugfix for builtin PitchToString function.

• Allow pitches out of 0..127 bounds, but keep in mind that HA can't handle them!
• PitchToString(11) gives 11, SMPitchToString(11) returns B-1

Does not handle microtonal accidentals.

Returns

string: Anglo-saxon note name followed by octave, e.g. "Ab5".

int: Accidental for the note, one of MSDefine NATURAL,FLAT,SHARP,DOUBLE_FLAT,DOUBLE_SHARP constants.

SMStringToPitch(string name)

Extension and bugfix for builtin StringToPitch function.

Does not handle microtonal accidentals.

• Allow pitches out of 0..127 bounds
• StringToPitch("B-1") gives the strange 71 result, SMStringToPitch("B-1") returns 11
• Handles double-sharp (## or x) and double-flat (bb)

Returns

int: May be out of 0..127 range.

int: Preferred accidental, one of AUTO, SHARP, FLAT... constants from MSDefine

EnterNumber(string text, number defaultValue, number minValue, number maxValue)

Ask the user to enter a number.

Use EnterString(...), and checks that the entered is a number within bounds. In case of error, ask again.

Return

number: or nil if user cancelled the choice.

See

EnterNumber2

EnterNumber2(string prompt, number minX, number maxX, number stepX, number factoryX, number currentX, boolean isInverted, boolean isVertical, string arrowsLocation, table args, function onChangeFunc, DisplayValueMask)

Ask the user to enter a number, in a more flexible and controlled way than the "EnterString" method, with possible realtime preview of result before validating the choice.

Return

number: X, nil if user cancelled the dialog

Errors

if minX >= maxX

if factoryX or currentX are outside of [minX:maxX] range

if factoryX and currentX are nil.

Example

 -- Create a new document with one staff, insert one note.
 -- This code moves the note horizontally
 -- X between -100% and 100%, step = 4.
 -- Factory position is 0, current is symbol head shift.
   Include "SMUtils"
 sym = FrontScore().FirstStaff.FirstSymbol
   x = EnterNumber2("Not horizontal shift",
    -100, 100, 4, 0, sym.HeadShift,
    false, false, nil, -- inverted, vertical, orientation
    {FrontScore(), sym},
    function(x, args)
      args[2].HeadShift = x
      args[1].Update()
    end,
    "%x %"
  )

EnterXY(string prompt, number minX, number maxX, number stepX, number factoryX, number currentX, number minY, number maxY, number stepY, number factoryY, number currentY, boolean invertXaxis, boolean invertYaxis, table args, function onChangeFunc, string displayValuesMask)

Ask the user to enter X,Y coordinates in a plotter with X and Y axis.

It's handy when you ask for 2 values, as X and Y offsets.

Returns

number: X, nil if user cancelled the dialog

number: Y, nil if user cancelled the dialog

Errors

if minX >= maxX or minY >= maxY

if factoryX or currentX are outside of [minX:maxX] range

if factoryY or currentY are outside of [minY:maxY] range

if factoryX and currentX, or factoryY and currentY are nil.

Example

 -- Create a new document with one staff, go to Page mode.
 -- This code moves first staff name position
 -- X between -50 and 50, Y between -30 and 30, steps are 1
 -- Negative Y go up, positive Y go down.
 -- Factory position is 0,0, current is 5,-24
   Include "SMUtils"
   x,y = EnterXY("Test XY",
    -50, 50, 1, 0, 5,
    -30, 30, 1, 0, -24,
    false, true, {FrontScore()},
    function(x,y,args)
      local staff = args[1].FirstStaff
      staff.TitleXOffset, staff.TitleYOffset = x, y
      Application.UpdateScores()
    end,
    "%x px, %y px" -- not mandatory, just show that unit is pixel (in 72 DPI)
  )

IsPowerOfTwo(number n)

Is n a number power of 2?

Return

boolean: true if n equals 1, 2, 4, 8, 16..., nil (for false) if not.

Error

if n is not a number

bin2int(string s, boolean signed)

Converts binary number (string containing only "0" and "1") to number.

Shortcut to tonumber(s, 2) with protection and no 32-bit limit

Return

int: 0 or positive integer

Error

if s is not a binary string

hex2int(string s, boolean signed)

Converts hexadecimal number (string containing 0-9a-fA-f) to number.

Shortcut to tonumber(s, 16) with protection and no 32-bit limit.

Return

int: 0 or positive integer

Error

if s is not an hexadecimal string

tohex(int n, int size, string separator)

Converts a number to hexadecimal string Shortcut to format("%x", n) with more options and no 32-bit limit

Return

string: string

Error

if n is not a number or size < 1 or separator is not a string.

tobin(int n, int size, string separator)

Converts a number to a binary string (containing only 0 and 1)

Return

string: string

Error

if n is not a number or size < 1 or separator is not a string.

BinNot(int a, int bits)

NOT bitwise operation MyrScript comes with BinAnd(...), BinOr(...), BinXor(...), BinShl(...), BinShr(...) but not the NOT bitwise operation.

Here it is!

Return

int: int

Example

 local a = 5 -- 0101
 print(bit_not(a, 4)) --> 10 (1010)

LinearScaling(number x, number a, number b, number c, number d)

Linear scaling (or linear transformation) of \(x\) from range \([a,b]\) to \([c,d]\).

Use case: convert a MIDI value between 0 and 127 to a number between 0% and 100%.

Return

number: \[ c + \frac{(d - c)(x - a)}{b - a} \]

Error

if \(a > b\), or \(c > d\), or \(x\) not in range \([a,b]\).

QuadraticScaling(number x, number a, number b, number c, number d)

Quadratic scaling of \(x\) from range \([a,b]\) to \([c,d]\).

Low values of \(x\) are compressed, high values are expanded.

Use case: a knob or cursor for reverb duration between 0 and 5 s. We need a more precise short duration (0.1 s, 0.3 s) than a longer one (no big difference between 4.5 s and 4.7 s).

Return

number: \[ c + (d - c) \left(\frac{x - a}{b - a}\right)^2 \]

Error

if \(a > b\), or \(c > d\), or \(x\) not in range \([a,b]\).

See

SquareRootScaling

PowerScaling

SquareRootScaling(number x, number a, number b, number c, number d)

Square root scaling of \(x\) from range \([a,b]\) to \([c,d]\).

Inverse of QuadraticScaling, high values of \(x\) are compressed, low values are expanded.

Return

number: \[ c + (d - c) \cdot \sqrt{\frac{x - a}{b - a}} \]

Error

if \(a > b\), or \(c > d\), or \(x\) not in range \([a,b]\).

See

QuadraticScaling

PowerScaling

PowerScaling(number x, number n, number a, number b, number c, number d)

Power scaling of \(x\) from range \([a,b]\) to \(x^n\) in \([c,d]\).

Flexible control of the non-linearity. QuadraticScaling use \(x^2\), here we add \(n\) argument:

• if \(n > 1\), low values are compressed, high values are expanded,
• if \(0 < n < 1\) low values are expanded, high values are compressed,
• if \(n = 1\) the scaling is linear.

Return

number: \[ c + (d - c) \cdot \left(\frac{x - a}{b - a}\right)^n \]

Error

if \(n \leq 0\), or \(a > b\), or \(c > d\), or \(x\) not in range \([a,b]\).