[转]Date and String Function in BluePrism

本文转自：https://www.codeproject.com/Articles/1247389/Date-and-String-Function-in-BluePrism

This article appears in the Third Party Products and Tools section. Articles in this section are for the members only and must not be used to promote or advertise products in any way, shape or form. Please report any spam or advertising.

Introduction

Date and String funtion are commonly used to take decision and do some calculations in BluePrism.

Expressions can be created in a variety of ways. They can be typed directly into the Expression Editor, or can be built up by dragging and dropping items from either the Function List, or the Data Item List. The Function List shows all the functions available in Blue Prism. When a Function is dragged and dropped into the Expression Editor, the default function text is automatically entered on the screen. Similarly, Data Items can be dragged in from the Data Item List and their names will be automatically entered into the Expression Editor.

Functions can also be composed in the Function Builder area in the centre of the screen. When a Function is selected from the Function List it is displayed in the Function Builder, along with a description of its use and any of its parameters. Parameters can be given values either by typing directly into the fields shown, or by dragging Data Items from the Data Item List. Once the Function has been built, it can be transferred to the Expression Editor using the Paste button.

A Calculation must specify the Data Item into which the evaluated result will be stored. The 'Store Result In' field can be populated by typing in a Data Item name, or by dragging in a Data Item from the list on the right.

When an expression is complete, it should be checked for errors and this can be done by selecting the 'Process Validation' button. Blue Prism will then check the expression and highlight the likely location of the error.

Using the code

Functions are in the formFunctionName(parameter1,parameter2), for example Mid("Hello", 1, 2).

The syntax for most functions is self-explanatory. Below are details of the more complex functions.

• DateDiff (interval,date1,date2)

  The recommended way to find the difference between two Dates, Times, or DateTimes is to subtract them

  For example, MakeDate(26,5,1999) - MakeDate(29,5,1968) will return a TimeSpan 11319.00:00:00

  When you need to find the difference in a non-fixed interval of time that can vary depending on the time of year, the DateDiff function provides some useful intervals. These are listed in the table within the function below. If date2 > date1 the returned number will be positive. If Week of year is used, the return value represents the number of weeks between the first day of the week containing date1 and the first day of the week containing date2.

  Parameters

  The three parameters are as follows:

  Interval

  A code specifying the desired units of the return value. These values are detailed in the function.

  date1

  The first of the two dates for comparison.

  date2

  The second of the two dates for comparison.

  Examples

  • To calculate the number of weeks between 29/5/1968 and 26/5/1999 use DateDiff(1,MakeDate(29,5,1968), MakeDate(26,5,1999)). This will correctly return 1617.

  • (interval, number,date)

    The recommended way to add an interval to a Date, Time, or DateTime is to add a TimeSpan

    For example, MakeDate(26,5,1999) + MakeTimeSpan(3, 0, 0, 0) would result in 29/05/1999.

    For times, MakeTime(12,30,0) + MakeTimeSpan(0, 1, 5, 3) would result in 13:35:03.

    When you need to add a non-fixed interval of time that can vary depending on the time of year the  function provides some useful intervals. Each type of interval is represented by the numbers listed below:

    

    As indicated some intervals are not applicable to the function but were chosen so the same set of numbers could be used for the function and the DateDiff function

    For example, to add a number of months to a date use interval number 5. So to add 2 months to 26/5/1999, use (5, 2, MakeDate(26,5,1999)). This would correctly return 26/7/1999.

    Intervals are subtracted in a similar manner by using a negative value for the quantity of intervals, ied(5, -2, MakeDate(26,5,1999)) results in 26/3/1999.

    The function won't return an invalid date. For example if you added 1 month to January 31st 2005 using (5,1,MakeDate(31,1,2005)) the function would return 28/2/2005 (rather than returning 31/02/2005 - a date which does not exist).

• FormatDate (Date, DateFormat);

  This function is used to format a date into a desired form, or to extract a smaller piece of information (such as the day of the week) from a full date.

  Parameters

  The two parameters are as follows:

             Date

             The date value to be formatted as a text value

             Format

             The format string, which specifies the form of the desired output. Possible values are outline                   below.

  Examples

  • FormatDate("19 Jul 2005", "yyyy-MM-dd") will return "2005-07-19"
  • FormatDate("19-07-2005","MMM dd, yyyy") returns "Jul 19, 2005"
  • FormatDate("19 Jul 2005", "dddd") will return "Tuesday"

Format String Details

The following date codes are supported. By combining values, you may form a suitable Format string, to                 be passed as the second parameter.

• MakeDate (Day, Month, Year);

  MakeDate() is used to create a date from numbers.

  Parameters

  The three parameters are as follows:

  Day

  The day of the month to be used. This must be valid with respect to the chosen month; 30 is not a valid value if the month is 2 (ie February)

  Month

  The 1-based index of the month desired (eg 4 corresponds to April). Must not exceed 12.

  Year

  The year desired, eg 2001.

  Two-digit Years

  For compatibility with old processes, where it was allowed, the MakeDate function will accept two-digit years and interpret them using the 2029 rule. However, it is strongly recommended that this functionality is never used. Always give a full year, including the century. In the case where the year is retrieved from another system in two digits, find out what convention that system is using and apply it as soon as you read the data.

  Examples

  Tips

  The MakeDate function is the preferred way to form a new date, rather than using a string such as "02/03/2007", which has an ambiguous value depending on the current locale (ie an American would probably interpret this date differently to a Briton).

  • MakeDate(21,6,2005) will return the date 21st June 2005
  • MakeDate(21,6,1995) will return the date 21st June 1995
  • MakeDate(5,12,29) will return the date 5th December 2029
  • MakeDate(5,12,30) will return the date 5th December 1930

• Mid (string, startpoint, maxcharacters);

  Mid() is used to reduce a longer string (ie sequence of letters) into a shorter string contained in that string (ie a substring). For example, Mid() can be used to reduce the string "Customer Name: John Smith", to the substring "John Smith".

  Parameters

  The three parameters are as follows:

  string

  The larger string, from which a substring is to be extracted.

  startpoint

  The 1-based index of the first letter desired.

  maxcharacters

  The maximum number of characters desired. The return value of the function will have this number of characters, unless the larger string ends first, in which case this value will become a theoretical maximum.

  Tips

  When the user-specified maximum length exceeds the length of the string supplied, Blue Prism will reduce this length to the length of the supplied string. Thus, to save counting too many letters, it is often convenient to write a large number in the last argument: Mid("Customer Name: John Smith", 16, 100). The string "John" could be obtained using Mid("Customer Name: John Smith",16,4). Note: The arguments are rounded off to whole integers, so Mid("abcdefg", 1.2, 1.8) would evaluate to "ab".

  Examples

  • Mid("Customer Name: John Smith", 16, 25) - returns "John Smith"

• Left (string, maxcharacters);

  Left() is used to return the first few letters of a longer string of letters.

  Parameters

  The two parameters are as follows:

  string

  The larger string, from which a substring is to be extracted.

  maxcharacters

  The maximum number of characters desired. The return value of the function will have this number of characters, unless the larger string ends first, in which case this value will become a theoretical maximum.

  Tips

  If the value maxcharacters exceeds (or indeed is equal to) the number of characters in the string, the function will simply return the string unmodified. The value supplied to maxcharacters may be zero if desired (returns empty string), but may not a negative number.

  Examples

  • Left("Blue Prism empowers business users to achieve more in less time", 10) returns "Blue Prism"

• Right (string, maxcharacters);

  Right() behaves exactly as Left(), but returns the ending string (with the specified length) rather than the starting string.

• Len (string);

  Len() returns the number of characters in a string. For example Len("Blue Prism") returns the number 10.

• Instr (string, substring);

  Instr() tests whether the smaller string substring is contained in the longer string string. If it is, then Instr() returns the number of characters from the left that the first occurrence of substring may be found.

  Parameters

  The two parameters are as follows:

  string

  The larger string, from which a substring is to be extracted.

  substring

  The smaller string, whose presence is to be detected in the larger string.

  Examples

  Tips

  If substring is not found in string then Instr() will return zero. Thus Instr() is a useful way of testing for the presence of a smaller string in a larger string: eg. Instr("Apples", "Bananas") > 0 will return FALSE.

  • Instr("Calculations are much faster with Blue Prism than with an abacus", "are") will return 14 because the word "are" first occurs at the fourteenth character.

• AddDays (date, numDays);

  This function will add a certain number of days to a chosen date.

  Parameters

  The two parameters are as follows:

  date

  The date to which onto which the days should be added.

  numDays

  The number of days to be added.

  Examples

  Tips

  As with the function(), only valid dates will be returned. For example in a leap year adding one day to 28 February will result in 29 February whereas during any other year it will result in 1 March.

  • AddDays("01/01/2006", 10) will return the date "11/01/2006".

• AddMonths (date, numMonths);

  This function will add a certain number of months to a chosen date.

  Parameters

  The two parameters are as follows:

  date

  The date to which onto which the months should be added.

  numMonths

  The number of months to be added.

  Examples

  Tips

  As with the function(), only valid dates will be returned. For example adding 1 month to January 31st 2005 using AddMonths("31/01/2005",1) would return "28/2/2005" (rather than returning "31/02/2005" - a date which does not exist).

  • AddMonths("01/01/2006", 10) will return the date "01/11/2006".

• Now ();

  This function will return the current date and time and date as a datetime data item.

  Tips

  If you merely want to know today's date, it would be better to use the Today() function instead.

• Today ();

  This function will return the current date as a date data item.

  Tips

  If you want to know the current time together with today's date, it might be better to use the Now() function instead.

• DecPad (number, numplaces);

  This function will represent a number in a text format. This is often useful when dealing with currency, when numbers such as the number 1 are more often represented as "1.00".

  Parameters

  The two parameters are as follows:

  number

  The number to be formatted as text.

  numPlaces

  The maximum number of decimal places desired.

  Examples

  Tips

  If the natural representation has too many decimal places then the appropriate number of decimal places will be removed, whilst rounding the number to the appropriate precision.

  • DecPad(1.296,2) will return the text "1.30".
  • DecPad(1.1111,2) will return the text "1.11"

• RndDn (number, numplaces);

  This function will round a number downwards to the desired number of decimal places. The datatype of the value returned is number.

  Parameters

  The two parameters are as follows:

  number

  The number to be rounded.

  numPlaces

  The maximum number of decimal places desired.

  Examples

  Tips

  If the number is already within the desired level of precision then it will remain unchanged, and in particular it will not be reformatted (as it would using the function DecPad). See also the functions Round and RndUp.

  • RndDn(9.19996,3) will return the number 9.199
  • RndDn(9.1345,2) will return the number 9.13
  • RndDn(3.14159,10) would return 3.14159 (the number is unchanged)

• RndUp (number, numplaces);

  This function will round a number upwards to the desired number of decimal places; it behaves analogously to the RndDn() function.

  Parameters

  The two parameters are as follows:

  number

  The number to be rounded.

  numPlaces

  The maximum number of decimal places desired.

  Examples

  Tips

  If the number is already within the desired level of precision then it will remain unchanged, and in particular it will not be reformatted (as it would using the function DecPad). See also the functions Round and RndDn.

  • RndDn(9.19996,3) will return the number 9.200
  • RndDn(9.1345,2) will return the number 9.14
  • RndDn(3.14159,10) would return 3.14159 (the number is unchanged)

• Round (number, numplaces);

  This function will round a number to the nearest number having the desired number of decimal places.

  Parameters

  The two parameters are as follows:

  number

  The number to be rounded.

  numPlaces

  The maximum number of decimal places desired.

  Examples

  Tips

  If the number is already within the desired level of precision then it will remain unchanged, and in particular it will not be reformatted (as it would using the function DecPad). See also the functions RndUp and RndDn.

  • Round(9.1345,2) will return the number 9.13
  • Round(9.19996,3) will return the number 9.200
  • Round(3.14159,10) would return 3.14159 (the number is unchanged)

• Sqrt (number);

  This function will return the square root of the supplied number. The square root of a number is the unique positive number which when multiplied by itself results in the number you started with.

  Examples

  • Sqrt(100) returns the number 10
  • Sqrt(2) returns 1.4142135623731

• Log (number, base);

  Evaluates the logarithm of the number to the specified base value. For a value v and a base b, the logarithm of v to the base b - written Log(v, b) - answers the question "what is the value x which satisfies b^x = v?".

  Examples

  • Log(1000, 10) = 3 because 10³ = 1000.
  • Log(1/4, 2) = -2 because 2^-2 = 1/4

• Chr (keycode);

  This function will return the character represented by the supplied ASCII code.

  Examples

  Tips

  For a full introduction to the ASCII code, please consult an external reference. A quick guide is given on the Blue Prism ASCII page.

  • Chr(65) returns the text "A"

• Upper (string);

  This function will return the upper case representation of the supplied text. Any letters in the supplied text which are already in upper case will be unchanged, whilst those which are not in upper case will be changed.

  Examples

  Tips

  See also the Lower() function.

  • Upper("software") will return the text "SOFTWARE"
  • Upper("aBcDeFg") will return the text "ABCDEFG"

• Lower (string);

  This function will return the lower case representation of the supplied text. Any letters in the supplied text which are already in lower case will be unchanged, whilst those which are not in lower case will be changed.

  Examples

  Tips

  See also the Upper() function.

  • Lower("SOFTWARE") will return the text "software"
  • Lower("aBcDeFg") will return the text "abcdefg"

 

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)