From 859b0ed46eb79975f879772d7edd6b08e2ec9a3c Mon Sep 17 00:00:00 2001 From: David Bond Date: Wed, 18 Oct 2023 18:38:20 +0100 Subject: [PATCH] Added minValue() and maxValue() --- .../MaxValueTests.cs | 35 + .../MinValueTests.cs | 35 + .../ExtendedExpression.cs | 6 + .../ExtensionFunction.cs | 2 + .../Extensions/MaxValue.cs | 34 + .../Extensions/MinValue.cs | 34 + .../PanoramicData.NCalcExtensions.csproj | 2 +- README.md | 848 +++++++++--------- global.json | 3 +- 9 files changed, 587 insertions(+), 412 deletions(-) create mode 100644 PanoramicData.NCalcExtensions.Test/MaxValueTests.cs create mode 100644 PanoramicData.NCalcExtensions.Test/MinValueTests.cs create mode 100644 PanoramicData.NCalcExtensions/Extensions/MaxValue.cs create mode 100644 PanoramicData.NCalcExtensions/Extensions/MinValue.cs diff --git a/PanoramicData.NCalcExtensions.Test/MaxValueTests.cs b/PanoramicData.NCalcExtensions.Test/MaxValueTests.cs new file mode 100644 index 0000000..82e79d7 --- /dev/null +++ b/PanoramicData.NCalcExtensions.Test/MaxValueTests.cs @@ -0,0 +1,35 @@ +namespace PanoramicData.NCalcExtensions.Test; + +public class MaxValueTests +{ + [Theory] + [InlineData("sbyte", sbyte.MaxValue)] + [InlineData("byte", byte.MaxValue)] + [InlineData("short", short.MaxValue)] + [InlineData("ushort", ushort.MaxValue)] + [InlineData("int", int.MaxValue)] + [InlineData("uint", uint.MaxValue)] + [InlineData("long", long.MaxValue)] + [InlineData("ulong", ulong.MaxValue)] + [InlineData("float", float.MaxValue)] + [InlineData("double", double.MaxValue)] + public void MaxValue_ReturnsExpectedValue(string type, object expectedOutput) + { + var expression = new ExtendedExpression($"maxValue('{type}')"); + expression.Evaluate().Should().BeEquivalentTo(expectedOutput); + } + + [Fact] + public void MaxValue_ForDecimal_ReturnsExpectedValue() + { + var expression = new ExtendedExpression($"maxValue('decimal')"); + expression.Evaluate().Should().BeEquivalentTo(decimal.MaxValue); + } + + [Fact] + public void MaxValue_ForUnsupportedType_ThrowsFormatException() + { + var expression = new ExtendedExpression($"maxValue('unsupportedType')"); + expression.Invoking(x => x.Evaluate()).Should().Throw(); + } +} \ No newline at end of file diff --git a/PanoramicData.NCalcExtensions.Test/MinValueTests.cs b/PanoramicData.NCalcExtensions.Test/MinValueTests.cs new file mode 100644 index 0000000..d54fac7 --- /dev/null +++ b/PanoramicData.NCalcExtensions.Test/MinValueTests.cs @@ -0,0 +1,35 @@ +namespace PanoramicData.NCalcExtensions.Test; + +public class MinValueTests +{ + [Theory] + [InlineData("sbyte", sbyte.MinValue)] + [InlineData("byte", byte.MinValue)] + [InlineData("short", short.MinValue)] + [InlineData("ushort", ushort.MinValue)] + [InlineData("int", int.MinValue)] + [InlineData("uint", uint.MinValue)] + [InlineData("long", long.MinValue)] + [InlineData("ulong", ulong.MinValue)] + [InlineData("float", float.MinValue)] + [InlineData("double", double.MinValue)] + public void MinValue_ReturnsExpectedValue(string type, object expectedOutput) + { + var expression = new ExtendedExpression($"minValue('{type}')"); + expression.Evaluate().Should().BeEquivalentTo(expectedOutput); + } + + [Fact] + public void MinValue_ForDecimal_ReturnsExpectedValue() + { + var expression = new ExtendedExpression($"minValue('decimal')"); + expression.Evaluate().Should().BeEquivalentTo(decimal.MinValue); + } + + [Fact] + public void MinValue_ForUnsupportedType_ThrowsFormatException() + { + var expression = new ExtendedExpression($"minValue('unsupportedType')"); + expression.Invoking(x => x.Evaluate()).Should().Throw(); + } +} \ No newline at end of file diff --git a/PanoramicData.NCalcExtensions/ExtendedExpression.cs b/PanoramicData.NCalcExtensions/ExtendedExpression.cs index 0b4b72e..652d2af 100644 --- a/PanoramicData.NCalcExtensions/ExtendedExpression.cs +++ b/PanoramicData.NCalcExtensions/ExtendedExpression.cs @@ -177,9 +177,15 @@ internal void Extend(string functionName, FunctionArgs functionArgs) case ExtensionFunction.Max: Max.Evaluate(functionArgs); return; + case ExtensionFunction.MaxValue: + MaxValue.Evaluate(functionArgs); + return; case ExtensionFunction.Min: Min.Evaluate(functionArgs); return; + case ExtensionFunction.MinValue: + MinValue.Evaluate(functionArgs); + return; case ExtensionFunction.NullCoalesce: NullCoalesce.Evaluate(functionArgs); return; diff --git a/PanoramicData.NCalcExtensions/ExtensionFunction.cs b/PanoramicData.NCalcExtensions/ExtensionFunction.cs index eeba2cd..9c3ea98 100644 --- a/PanoramicData.NCalcExtensions/ExtensionFunction.cs +++ b/PanoramicData.NCalcExtensions/ExtensionFunction.cs @@ -43,7 +43,9 @@ public static class ExtensionFunction public const string List = "list"; public const string ListOf = "listOf"; public const string Max = "max"; + public const string MaxValue = "maxValue"; public const string Min = "min"; + public const string MinValue = "minValue"; public const string NewJObject = "jObject"; public const string NullCoalesce = "nullCoalesce"; public const string OrderBy = "orderBy"; diff --git a/PanoramicData.NCalcExtensions/Extensions/MaxValue.cs b/PanoramicData.NCalcExtensions/Extensions/MaxValue.cs new file mode 100644 index 0000000..eacdfea --- /dev/null +++ b/PanoramicData.NCalcExtensions/Extensions/MaxValue.cs @@ -0,0 +1,34 @@ +namespace PanoramicData.NCalcExtensions.Extensions; + +internal static class MaxValue +{ + private const string ErrorMessage = $"{ExtensionFunction.MaxValue} takes exactly one string parameter, which must be one of 'sbyte', 'byte', 'short', 'ushort', 'int', 'uint', 'long', 'ulong', 'float', 'double' or 'decimal'."; + + internal static void Evaluate(FunctionArgs functionArgs) + { + var originalList = functionArgs.Parameters[0].Evaluate(); + + if (functionArgs.Parameters.Length != 1) + { + throw new FormatException(ErrorMessage); + } + + functionArgs.Result = originalList switch + { + "sbyte" => sbyte.MaxValue, + "byte" => byte.MaxValue, + "short" => short.MaxValue, + "ushort" => ushort.MaxValue, + "int" => int.MaxValue, + "uint" => uint.MaxValue, + "long" => long.MaxValue, + "ulong" => ulong.MaxValue, + "float" => float.MaxValue, + "double" => double.MaxValue, + "decimal" => decimal.MaxValue, + _ => throw new FormatException(ErrorMessage) + }; + + return; + } +} diff --git a/PanoramicData.NCalcExtensions/Extensions/MinValue.cs b/PanoramicData.NCalcExtensions/Extensions/MinValue.cs new file mode 100644 index 0000000..edafadc --- /dev/null +++ b/PanoramicData.NCalcExtensions/Extensions/MinValue.cs @@ -0,0 +1,34 @@ +namespace PanoramicData.NCalcExtensions.Extensions; + +internal static class MinValue +{ + private const string ErrorMessage = $"{ExtensionFunction.MinValue} takes exactly one string parameter, which must be one of 'sbyte', 'byte', 'short', 'ushort', 'int', 'uint', 'long', 'ulong', 'float', 'double' or 'decimal'."; + + internal static void Evaluate(FunctionArgs functionArgs) + { + var originalList = functionArgs.Parameters[0].Evaluate(); + + if (functionArgs.Parameters.Length != 1) + { + throw new FormatException(ErrorMessage); + } + + functionArgs.Result = originalList switch + { + "sbyte" => sbyte.MinValue, + "byte" => byte.MinValue, + "short" => short.MinValue, + "ushort" => ushort.MinValue, + "int" => int.MinValue, + "uint" => uint.MinValue, + "long" => long.MinValue, + "ulong" => ulong.MinValue, + "float" => float.MinValue, + "double" => double.MinValue, + "decimal" => decimal.MinValue, + _ => throw new FormatException(ErrorMessage) + }; + + return; + } +} diff --git a/PanoramicData.NCalcExtensions/PanoramicData.NCalcExtensions.csproj b/PanoramicData.NCalcExtensions/PanoramicData.NCalcExtensions.csproj index f8d3ea9..d754e35 100644 --- a/PanoramicData.NCalcExtensions/PanoramicData.NCalcExtensions.csproj +++ b/PanoramicData.NCalcExtensions/PanoramicData.NCalcExtensions.csproj @@ -24,7 +24,7 @@ true portable - Added support for count(String x). + Added support for minValue() and maxValue(). snupkg diff --git a/README.md b/README.md index 7c49ae0..76d6e2e 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,9 @@ The NCalc documentation can be found [here (source code)](https://github.com/skl | [list()](#list) | Emits a List and collapses down lists of lists to a single list. | | [listOf()](#listof) | Emits a List<T>. | | [max()](#max) | Emits the maximum value, ignoring nulls. | +| [maxValue()](#maxValue) | Emits the maximum possible value for a given numeric type. | | [min()](#min) | Emits the minimum value, ignoring nulls. | +| [minValue()](#minValue) | Emits the minimum possible value for a given numeric type. | | [nullCoalesce()](#nullcoalesce) | Returns the first parameter that is not null, otherwise: null. | | [orderBy()](#orderby) | Orders an IEnumerable by one or more lambda expressions. | | [padLeft()](#padleft) | Pad the left of a string with a character to a desired string length. | @@ -760,579 +762,605 @@ Emits a List and collapses down lists of lists to a single list. #### Purpose Emits a List<T>. -#### Parameters - * the type - * the parameters + #### Parameters + * the type + * the parameters -#### Examples - * listOf('object?', '', 1, '0') - * listOf('object?', null, 1, '0') - * listOf('int?', 1, null, 3) - * listOf('string', '1', '2', 3) : throws an exception ---- + #### Examples + * listOf('object?', '', 1, '0') + * listOf('object?', null, 1, '0') + * listOf('int?', 1, null, 3) + * listOf('string', '1', '2', 3) : throws an exception + --- -### max() + ### max() -#### Purpose -Emits the maximum value, ignoring nulls. + #### Purpose + Emits the maximum value, ignoring nulls. -#### Parameters - * the list - * optionally, a pair of parameters providing a lambda expression to be evaluated. + #### Parameters + * the list + * optionally, a pair of parameters providing a lambda expression to be evaluated. -#### Examples - * max(listOf('int?', 1, null, 3)) : 3 - * max(listOf('int', 1, 2, 3), 'x', 'x + 1') : 4 - * max(listOf('string', '1', '2', '3')) : '3' - * max(listOf('string', '1', '2', '3'), 'x', 'x + x') : '33' ---- + #### Examples + * max(listOf('int?', 1, null, 3)) : 3 + * max(listOf('int', 1, 2, 3), 'x', 'x + 1') : 4 + * max(listOf('string', '1', '2', '3')) : '3' + * max(listOf('string', '1', '2', '3'), 'x', 'x + x') : '33' + --- -### min() + ### maxValue() -#### Purpose -Emits the minimum value, ignoring nulls. + #### Purpose + Emits the maximum possible value for a given numeric type. -#### Parameters - * the list - * optionally, a pair of parameters providing a lambda expression to be evaluated. + #### Parameters + * a string representing the type, which must be one of 'sbyte', 'byte', 'short', 'ushort', 'int', 'uint', 'long', 'ulong', 'float', 'double' or 'decimal'. -#### Examples - * min(listOf('int?', 1, null, 3)) : 1 - * min(listOf('int', 1, 2, 3), 'x', 'x + 1') : 2 - * min(listOf('string', '1', '2', '3')) : '1' - * min(listOf('string', '1', '2', '3'), 'x', 'x + x') : '11' + #### Examples + * maxValue('byte') : (byte)255 + * maxValue('ushort') : (ushort)65535 + --- ---- + ### min() -### nullCoalesce() + #### Purpose + Emits the minimum value, ignoring nulls. -#### Purpose -Returns the first parameter that is not null, otherwise: null. + #### Parameters + * the list + * optionally, a pair of parameters providing a lambda expression to be evaluated. -#### Parameters - * any number of objects + #### Examples + * min(listOf('int?', 1, null, 3)) : 1 + * min(listOf('int', 1, 2, 3), 'x', 'x + 1') : 2 + * min(listOf('string', '1', '2', '3')) : '1' + * min(listOf('string', '1', '2', '3'), 'x', 'x + x') : '11' + --- + + ### minValue() -#### Examples - * nullCoalesce() : null - * nullCoalesce(1, null) : 1 - * nullCoalesce(null, 1, 2, 3) : 1 - * nullCoalesce(null, null, null) : null - * nullCoalesce(null, null, 'xxx', 3) : 'xxx' + #### Purpose + Emits the minimum possible value for a given numeric type. ---- + #### Parameters + * a string representing the type, which must be one of 'sbyte', 'byte', 'short', 'ushort', 'int', 'uint', 'long', 'ulong', 'float', 'double' or 'decimal'. -### orderBy() + #### Examples + * minValue('byte') : (byte)0 + * minValue('ushort') : (ushort)0 -#### Purpose -Orders an IEnumerable by one or more lambda expressions. + --- -#### Parameters - * list - the original list - * predicate - a string to represent the value to be evaluated - * nCalcString1 - the first orderBy lambda expression - * nCalcString2 (optional) - the next orderBy lambda expression - * nCalcString... (optional) - the next orderBy lambda expression + ### nullCoalesce() -#### Examples - * orderBy(list(34, 33, 2, 1), 'n', 'n') : list(1, 2, 33, 34) - * orderBy(list(34, 33, 2, 1), 'n', '-n') : list(34, 33, 2, 1) - * orderBy(list(34, 33, 2, 1), 'n % 32', 'n % 2') : list(34, 33, 1, 2) - * orderBy(list(34, 33, 2, 1), 'n % 2', 'n % 32') : list(33, 1, 34, 2) + #### Purpose + Returns the first parameter that is not null, otherwise: null. ---- + #### Parameters + * any number of objects -### padLeft() + #### Examples + * nullCoalesce() : null + * nullCoalesce(1, null) : 1 + * nullCoalesce(null, 1, 2, 3) : 1 + * nullCoalesce(null, null, null) : null + * nullCoalesce(null, null, 'xxx', 3) : 'xxx' -#### Purpose -Pad the left of a string with a character to a desired string length. + --- -#### Parameters - * stringToPad - * desiredStringLength (must be >=1) - * paddingCharacter + ### orderBy() -#### Examples - * padLeft('', 1, '0') : '0' - * padLeft('12', 5, '0') : '00012' - * padLeft('12345', 5, '0') : '12345' - * padLeft('12345', 3, '0') : '12345' + #### Purpose + Orders an IEnumerable by one or more lambda expressions. ---- + #### Parameters + * list - the original list + * predicate - a string to represent the value to be evaluated + * nCalcString1 - the first orderBy lambda expression + * nCalcString2 (optional) - the next orderBy lambda expression + * nCalcString... (optional) - the next orderBy lambda expression -### parse() + #### Examples + * orderBy(list(34, 33, 2, 1), 'n', 'n') : list(1, 2, 33, 34) + * orderBy(list(34, 33, 2, 1), 'n', '-n') : list(34, 33, 2, 1) + * orderBy(list(34, 33, 2, 1), 'n % 32', 'n % 2') : list(34, 33, 1, 2) + * orderBy(list(34, 33, 2, 1), 'n % 2', 'n % 32') : list(33, 1, 34, 2) -#### Purpose -Returns the conversion of a string to a numeric type. Supported types are: - * bool - * sbyte - * byte - * short - * ushort - * int - * uint - * long - * ulong - * double - * float - * decimal - * JArray (jArray also supported for backaward compatibility) - * JObject (jObject also supported for backaward compatibility) - * Guid + --- -#### Parameters - * type (see above) - * text - * valueIfParseFails (optional) + ### padLeft() -#### Examples - * parse('int', '1') : 1 - * parse('bool', 'x', null) : null - * parse('jObject', '{ "a" : 1 }', null) : null - * parse('jArray', '[ { "a" : 1 } ]', null) : null ---- + #### Purpose + Pad the left of a string with a character to a desired string length. -### parseInt() + #### Parameters + * stringToPad + * desiredStringLength (must be >=1) + * paddingCharacter -#### Purpose -Returns an integer version of a string. + #### Examples + * padLeft('', 1, '0') : '0' + * padLeft('12', 5, '0') : '00012' + * padLeft('12345', 5, '0') : '12345' + * padLeft('12345', 3, '0') : '12345' -#### Parameters - * integerAsString + --- -#### Examples - * parseInt('1') : 1 + ### parse() ---- + #### Purpose + Returns the conversion of a string to a numeric type. Supported types are: + * bool + * sbyte + * byte + * short + * ushort + * int + * uint + * long + * ulong + * double + * float + * decimal + * JArray (jArray also supported for backaward compatibility) + * JObject (jObject also supported for backaward compatibility) + * Guid -### regexGroup() + #### Parameters + * type (see above) + * text + * valueIfParseFails (optional) -#### Purpose -Selects a regex group capture + #### Examples + * parse('int', '1') : 1 + * parse('bool', 'x', null) : null + * parse('jObject', '{ "a" : 1 }', null) : null + * parse('jArray', '[ { "a" : 1 } ]', null) : null + --- -#### Parameters - * input - * regex - * zero-based capture index (default: 0) + ### parseInt() -#### Examples - * regexGroup('abcdef', '^ab(.+?)f$') : 'cde' - * regexGroup('abcdef', '^ab(.)+f$') : 'c' - * regexGroup('abcdef', '^ab(.)+f$', 1) : 'd' - * regexGroup('abcdef', '^ab(.)+f$', 2) : 'e' - * regexGroup('abcdef', '^ab(.)+f$', 10) : null + #### Purpose + Returns an integer version of a string. ---- + #### Parameters + * integerAsString -### regexIsMatch() + #### Examples + * parseInt('1') : 1 -#### Purpose -Determine whether a string matches a regex + --- -#### Parameters - * input - * regex + ### regexGroup() -#### Examples - * regexIsMatch('abcdef', '^ab.+') : true - * regexIsMatch('Zbcdef', '^ab.+') : false + #### Purpose + Selects a regex group capture ---- + #### Parameters + * input + * regex + * zero-based capture index (default: 0) -### replace() + #### Examples + * regexGroup('abcdef', '^ab(.+?)f$') : 'cde' + * regexGroup('abcdef', '^ab(.)+f$') : 'c' + * regexGroup('abcdef', '^ab(.)+f$', 1) : 'd' + * regexGroup('abcdef', '^ab(.)+f$', 2) : 'e' + * regexGroup('abcdef', '^ab(.)+f$', 10) : null -#### Purpose -Replace a string with another string + --- -#### Parameters - * haystackString - * needleString - * betterNeedleString + ### regexIsMatch() -#### Examples - * replace('abcdefg', 'cde', 'CDE') : 'abCDEfg' - * replace('abcdefg', 'cde', '') : 'abfg' + #### Purpose + Determine whether a string matches a regex ---- + #### Parameters + * input + * regex -### retrieve() + #### Examples + * regexIsMatch('abcdef', '^ab.+') : true + * regexIsMatch('Zbcdef', '^ab.+') : false -#### Purpose -Retrieves a value from storage + --- -#### Parameters - * key + ### replace() -#### Examples - * retrieve('thing') + #### Purpose + Replace a string with another string ---- + #### Parameters + * haystackString + * needleString + * betterNeedleString -### select() + #### Examples + * replace('abcdefg', 'cde', 'CDE') : 'abCDEfg' + * replace('abcdefg', 'cde', '') : 'abfg' -#### Purpose -Converts an IEnumerable using a lambda. + --- -#### Parameters - * list - the original list - * predicate - a string to represent the value to be evaluated - * nCalcString - the value to evaluate to for each item in the list - * output list type - outputs a list of the specified type (optional) + ### retrieve() -#### Examples - * select(list(1, 2, 3, 4, 5), 'n', 'n + 1') : list(2, 3, 4, 5, 6) - * select(list(jObject('a', 1, 'b', '2'), jObject('a', 3, 'b', '4')), 'n', 'n', 'JObject') : list of JObjects + #### Purpose + Retrieves a value from storage ---- + #### Parameters + * key -### selectDistinct() + #### Examples + * retrieve('thing') -#### Purpose -Converts an IEnumerable using a lambda and removes duplicates. + --- -#### Parameters - * list - the original list - * predicate - a string to represent the value to be evaluated - * nCalcString - the value to evaluate to for each item in the list + ### select() -#### Examples - * selectDistinct(list(1, 2, 3, 3, 3), 'n', 'n + 1') : list(2, 3, 4) + #### Purpose + Converts an IEnumerable using a lambda. ---- + #### Parameters + * list - the original list + * predicate - a string to represent the value to be evaluated + * nCalcString - the value to evaluate to for each item in the list + * output list type - outputs a list of the specified type (optional) -### setProperties() + #### Examples + * select(list(1, 2, 3, 4, 5), 'n', 'n + 1') : list(2, 3, 4, 5, 6) + * select(list(jObject('a', 1, 'b', '2'), jObject('a', 3, 'b', '4')), 'n', 'n', 'JObject') : list of JObjects -#### Purpose -Sets properties on an existing object. + --- -#### Parameters - * object - the original object - * property1 - the first new property name - * value1 - the first new property value - * propertyN (optional) - the nth new property name - * valueN (optional) - the nth new property value -#### Examples - * setProperties(jObject('a', 1, 'b', null), 'c', 'X') : jObject('a', 1, 'b', null, 'c', 'X') - * setProperties(jObject('a', 1, 'b', null), 'c', 'X', 'd', 'Y') : jObject('a', 1, 'b', null, 'c', 'X', 'd', 'Y') ---- + ### selectDistinct() -### skip() + #### Purpose + Converts an IEnumerable using a lambda and removes duplicates. -#### Purpose -Skips a number of items in a list. + #### Parameters + * list - the original list + * predicate - a string to represent the value to be evaluated + * nCalcString - the value to evaluate to for each item in the list -#### Notes -If the number of items to skip is greater than the number of items in the list, an empty list is returned. + #### Examples + * selectDistinct(list(1, 2, 3, 3, 3), 'n', 'n + 1') : list(2, 3, 4) -#### Parameters - * the list to skip from - * the number of items to skip + --- -#### Examples - * skip(list(1, 2, 3), 1): list(2, 3) + ### setProperties() ---- + #### Purpose + Sets properties on an existing object. -### sort() + #### Parameters + * object - the original object + * property1 - the first new property name + * value1 - the first new property value + * propertyN (optional) - the nth new property name + * valueN (optional) - the nth new property value + #### Examples + * setProperties(jObject('a', 1, 'b', null), 'c', 'X') : jObject('a', 1, 'b', null, 'c', 'X') + * setProperties(jObject('a', 1, 'b', null), 'c', 'X', 'd', 'Y') : jObject('a', 1, 'b', null, 'c', 'X', 'd', 'Y') + --- -#### Purpose -Sorts an IComparable ascending or descending. + ### skip() -#### Parameters - * list - the original list - * direction (optional) - 'asc' is the default, 'desc' is the other option -#### Examples - * sort(list(2, 1, 3)) : list(1, 2, 3) - * sort(list(2, 1, 3), 'asc') : list(1, 2, 3) - * sort(list(2, 1, 3), 'desc') : list(3, 2, 1) - * sort(list('b', 'a', 'c'))) : list('a', 'b', 'c') + #### Purpose + Skips a number of items in a list. ---- + #### Notes + If the number of items to skip is greater than the number of items in the list, an empty list is returned. -### split() + #### Parameters + * the list to skip from + * the number of items to skip -#### Purpose -Splits a string on a given character into a list of strings. + #### Examples + * skip(list(1, 2, 3), 1): list(2, 3) -#### Parameters - * longString - * character + --- -#### Examples - * split('a bc d', ' ') : list('a', 'bc', 'd') + ### sort() ---- + #### Purpose + Sorts an IComparable ascending or descending. -### startsWith() + #### Parameters + * list - the original list + * direction (optional) - 'asc' is the default, 'desc' is the other option + #### Examples + * sort(list(2, 1, 3)) : list(1, 2, 3) + * sort(list(2, 1, 3), 'asc') : list(1, 2, 3) + * sort(list(2, 1, 3), 'desc') : list(3, 2, 1) + * sort(list('b', 'a', 'c'))) : list('a', 'b', 'c') -#### Purpose -Determines whether a string starts with another string. + --- -#### Parameters - * longString - * shortString + ### split() -#### Examples - * startsWith('abcdefg', 'ab') : true - * startsWith('abcdefg', 'cd') : false + #### Purpose + Splits a string on a given character into a list of strings. ---- + #### Parameters + * longString + * character -### store() + #### Examples + * split('a bc d', ' ') : list('a', 'bc', 'd') -#### Purpose -Stores a value for use later in the pipeline + --- -#### Returns + ### startsWith() -true + #### Purpose + Determines whether a string starts with another string. -#### Parameters - * key - * value + #### Parameters + * longString + * shortString -#### Examples - * store('thing', 1) : true + #### Examples + * startsWith('abcdefg', 'ab') : true + * startsWith('abcdefg', 'cd') : false ---- + --- -### substring() + ### store() -#### Purpose -Retrieves part of a string. If more characters are requested than available at the end of the string, just the available characters are returned. + #### Purpose + Stores a value for use later in the pipeline -#### Parameters - * inputString - * startIndex - * length (optional) + #### Returns -#### Examples - * substring('haystack', 3) : 'stack' - * substring('haystack', 0, 3) : 'hay' - * substring('haystack', 3, 100) : 'stack' - * substring('haystack', 0, 100) : 'haystack' - * substring('haystack', 0, 0) : '' + true ---- + #### Parameters + * key + * value -### sum() + #### Examples + * store('thing', 1) : true -#### Purpose -Sums numeric items. Optionally, perform a lambda on each one first. + --- -#### Parameters - * list - the original list - * predicate (optional) - a string to represent the value to be evaluated - * nCalcString (optional) - the string to evaluate + ### substring() -#### Examples - * sum(list(1, 2, 3)) : 6 - * sum(list(1, 2, 3), 'n', 'n * n') : 14 + #### Purpose + Retrieves part of a string. If more characters are requested than available at the end of the string, just the available characters are returned. ---- + #### Parameters + * inputString + * startIndex + * length (optional) -### switch() + #### Examples + * substring('haystack', 3) : 'stack' + * substring('haystack', 0, 3) : 'hay' + * substring('haystack', 3, 100) : 'stack' + * substring('haystack', 0, 100) : 'haystack' + * substring('haystack', 0, 0) : '' -#### Purpose -Return one of a number of values, depending on the input function. + --- -#### Parameters - * switched value - * a set of pairs: case_n, output_n - * if present, a final value can be used as a default. If the default WOULD have been returned, but no default is present, an exception is thrown. + ### sum() -#### Examples - * switch('yes', 'yes', 1, 'no', 2) : 1 - * switch('blah', 'yes', 1, 'no', 2) : throws exception - * switch('blah', 'yes', 1, 'no', 2, 3) : 3 + #### Purpose + Sums numeric items. Optionally, perform a lambda on each one first. ---- + #### Parameters + * list - the original list + * predicate (optional) - a string to represent the value to be evaluated + * nCalcString (optional) - the string to evaluate -### take() + #### Examples + * sum(list(1, 2, 3)) : 6 + * sum(list(1, 2, 3), 'n', 'n * n') : 14 -#### Purpose -Takes a number of items from a list. + --- -#### Notes -If a number is provided that is longer than the list, the full list is returned. + ### switch() -#### Parameters - * the list to take from - * the number of items to take + #### Purpose + Return one of a number of values, depending on the input function. -#### Examples - * take(list(1, 2, 3), 2): list(1, 2) - * take(list(1, 2, 3), 10): list(1, 2, 3) + #### Parameters + * switched value + * a set of pairs: case_n, output_n + * if present, a final value can be used as a default. If the default WOULD have been returned, but no default is present, an exception is thrown. ---- + #### Examples + * switch('yes', 'yes', 1, 'no', 2) : 1 + * switch('blah', 'yes', 1, 'no', 2) : throws exception + * switch('blah', 'yes', 1, 'no', 2, 3) : 3 -### throw() + --- -#### Purpose -Throws an NCalcExtensionsException. Useful in an if(). + ### take() -#### Parameters - * message (optional) + #### Purpose + Takes a number of items from a list. -#### Examples - * throw() - * throw('This is a message') - * if(problem, throw('There is a problem'), 5) + #### Notes + If a number is provided that is longer than the list, the full list is returned. ---- + #### Parameters + * the list to take from + * the number of items to take -### timeSpan() + #### Examples + * take(list(1, 2, 3), 2): list(1, 2) + * take(list(1, 2, 3), 10): list(1, 2, 3) -#### Purpose -Determines the amount of time between two DateTimes. -The following units are supported: - * Years - * Weeks - * Days - * Hours - * Minutes - * Seconds - * Milliseconds - * Any other string is handled with TimeSpan.ToString(timeUnit). See https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-timespan-format-strings + --- -#### Parameters - * startDateTime - * endDateTime - * timeUnit + ### throw() -#### Examples - * timeSpan('2019-01-01 00:01:00', '2019-01-01 00:02:00', 'seconds') : 3600 + #### Purpose + Throws an NCalcExtensionsException. Useful in an if(). ---- + #### Parameters + * message (optional) -### toDateTime() + #### Examples + * throw() + * throw('This is a message') + * if(problem, throw('There is a problem'), 5) -#### Purpose -Converts a string to a UTC DateTime. May take an optional inputTimeZone. + --- -#### Notes -When using numbers as the first input parameter, provide it as a decimal (see examples, below) -to avoid hitting an NCalc bug relating to longs being interpreted as floats. + ### timeSpan() -#### Parameters - * inputString - * stringFormat - * inputTimeZone (optional) See https://docs.microsoft.com/en-us/dotnet/api/system.timezoneinfo.findsystemtimezonebyid?view=netstandard-2.0 + #### Purpose + Determines the amount of time between two DateTimes. + The following units are supported: + * Years + * Weeks + * Days + * Hours + * Minutes + * Seconds + * Milliseconds + * Any other string is handled with TimeSpan.ToString(timeUnit). See https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-timespan-format-strings -#### Examples - * toDateTime('2019-01-01', 'yyyy-MM-dd') : A date time representing 2019-01-01 - * toDateTime('2020-02-29 12:00', 'yyyy-MM-dd HH:mm', 'Eastern Standard Time') : A date time representing 2020-02-29 17:00:00 UTC - * toDateTime('2020-03-13 12:00', 'yyyy-MM-dd HH:mm', 'Eastern Standard Time') : A date time representing 2020-03-13 16:00:00 UTC - * toDateTime(161827200.0, 's', 'UTC') : A date time representing 1975-02-17 00:00:00 UTC - * toDateTime(156816000000.0, 'ms', 'UTC') : A date time representing 1974-12-21 00:00:00 UTC - * toDateTime(156816000000000.0, 'us', 'UTC') : A date time representing 1974-12-21 00:00:00 UTC + #### Parameters + * startDateTime + * endDateTime + * timeUnit ---- + #### Examples + * timeSpan('2019-01-01 00:01:00', '2019-01-01 00:02:00', 'seconds') : 3600 -### toLower() + --- -#### Purpose -Converts a string to lower case. + ### toDateTime() -#### Parameters - * string + #### Purpose + Converts a string to a UTC DateTime. May take an optional inputTimeZone. -#### Examples - * toLower('PaNToMIMe') : 'pantomime' + #### Notes + When using numbers as the first input parameter, provide it as a decimal (see examples, below) + to avoid hitting an NCalc bug relating to longs being interpreted as floats. ---- + #### Parameters + * inputString + * stringFormat + * inputTimeZone (optional) See https://docs.microsoft.com/en-us/dotnet/api/system.timezoneinfo.findsystemtimezonebyid?view=netstandard-2.0 -### toString() + #### Examples + * toDateTime('2019-01-01', 'yyyy-MM-dd') : A date time representing 2019-01-01 + * toDateTime('2020-02-29 12:00', 'yyyy-MM-dd HH:mm', 'Eastern Standard Time') : A date time representing 2020-02-29 17:00:00 UTC + * toDateTime('2020-03-13 12:00', 'yyyy-MM-dd HH:mm', 'Eastern Standard Time') : A date time representing 2020-03-13 16:00:00 UTC + * toDateTime(161827200.0, 's', 'UTC') : A date time representing 1975-02-17 00:00:00 UTC + * toDateTime(156816000000.0, 'ms', 'UTC') : A date time representing 1974-12-21 00:00:00 UTC + * toDateTime(156816000000000.0, 'us', 'UTC') : A date time representing 1974-12-21 00:00:00 UTC -#### Purpose -Converts any object to a string + --- -#### Parameters - * object - * format (optional) + ### toLower() -#### Examples - * toString(1) : '1' - * toString(1000, 'N2') : '1,000.00' - * toString(DateTimeOffset, 'yyyy-MM-dd') : '2023-02-17' + #### Purpose + Converts a string to lower case. ---- + #### Parameters + * string -### toUpper() + #### Examples + * toLower('PaNToMIMe') : 'pantomime' -#### Purpose -Converts a string to upper case. + --- -#### Parameters - * string + ### toString() -#### Examples - * toUpper('PaNToMIMe') : 'PANTOMIME' + #### Purpose + Converts any object to a string ---- + #### Parameters + * object + * format (optional) -### try() + #### Examples + * toString(1) : '1' + * toString(1000, 'N2') : '1,000.00' + * toString(DateTimeOffset, 'yyyy-MM-dd') : '2023-02-17' -#### Purpose -If a function throws an exception, return an alternate value. + --- -#### Parameters - * function to attempt - * result to return if an exception is thrown (null is returned if this parameter is omitted and an exception is thrown) + ### toUpper() -#### Examples - * try(1, 'Failed') : 1 - * try(throw('Woo')) : null - * try(throw('Woo'), 'Failed') : 'Failed' - * try(throw('Woo'), exception_message) : 'Woo' - * try(throw('Woo'), exception_type) : typeof(PanoramicData.NCalcExtensions.Exceptions.NCalcExtensionsException) - * try(throw('Woo'), exception_typeFullName) : 'PanoramicData.NCalcExtensions.Exceptions.NCalcExtensionsException' - * try(throw('Woo'), exception_typeName) : 'NCalcExtensionsException' - * try(throw('Woo'), exception) : The Exception object thrown by the throw function. + #### Purpose + Converts a string to upper case. ---- + #### Parameters + * string -### tryParse() + #### Examples + * toUpper('PaNToMIMe') : 'PANTOMIME' -#### Purpose -Returns a boolean result of an attempted cast. + --- -#### Parameters - * type - * value - * key - for use with the retrieve() function + ### try() -#### Examples - * tryParse('int', '1', 'outputVariable') : true - * tryParse('int', 'string', 'outputVariable') : false + #### Purpose + If a function throws an exception, return an alternate value. ---- + #### Parameters + * function to attempt + * result to return if an exception is thrown (null is returned if this parameter is omitted and an exception is thrown) -### typeOf() + #### Examples + * try(1, 'Failed') : 1 + * try(throw('Woo')) : null + * try(throw('Woo'), 'Failed') : 'Failed' + * try(throw('Woo'), exception_message) : 'Woo' + * try(throw('Woo'), exception_type) : typeof(PanoramicData.NCalcExtensions.Exceptions.NCalcExtensionsException) + * try(throw('Woo'), exception_typeFullName) : 'PanoramicData.NCalcExtensions.Exceptions.NCalcExtensionsException' + * try(throw('Woo'), exception_typeName) : 'NCalcExtensionsException' + * try(throw('Woo'), exception) : The Exception object thrown by the throw function. -#### Purpose -Determines the C# type of the object. + --- -#### Parameters - * parameter + ### tryParse() -#### Examples - * typeOf('text') : 'String' - * typeOf(1) : 'Int32' - * typeOf(1.1) : 'Double' - * typeOf(null) : null + #### Purpose + Returns a boolean result of an attempted cast. ---- + #### Parameters + * type + * value + * key - for use with the retrieve() function -### where() + #### Examples + * tryParse('int', '1', 'outputVariable') : true + * tryParse('int', 'string', 'outputVariable') : false -#### Purpose -Filters an IEnumerable to bring back only those items that match a condition. + --- -#### Parameters - * list - the original list - * predicate - a string to represent the value to be evaluated - * nCalcString - the string to evaluate + ### typeOf() -#### Examples - * where(list(1, 2, 3, 4, 5), 'n', 'n < 3') : list(1, 2) + #### Purpose + Determines the C# type of the object. + + #### Parameters + * parameter + + #### Examples + * typeOf('text') : 'String' + * typeOf(1) : 'Int32' + * typeOf(1.1) : 'Double' + * typeOf(null) : null + + --- + + ### where() + + #### Purpose + Filters an IEnumerable to bring back only those items that match a condition. + + #### Parameters + * list - the original list + * predicate - a string to represent the value to be evaluated + * nCalcString - the string to evaluate + + #### Examples + * where(list(1, 2, 3, 4, 5), 'n', 'n < 3') : list(1, 2) * where(list(1, 2, 3, 4, 5), 'n', 'n < 3 || n > 4') : list(1, 2, 5) diff --git a/global.json b/global.json index e45ecad..20a9854 100644 --- a/global.json +++ b/global.json @@ -1,5 +1,6 @@ { "sdk": { - "version": "7.0.200" + "version": "7.0.307", + "rollForward": "latestFeature" } } \ No newline at end of file