Your guide to working with Strings in Xplan
All about strings
Strings are one of the most common data types you will work with in Xplan and your Xmerge coding.
Examples of built in strings you have likely seen or used already include: the client’s name, address details and goal descriptions – all of those are stored and represented as strings.
Strings themselves may just be bits of text (made up of characters) but that doesn’t mean we can’t do a range of things with them to:
- manipulate the data;
- to increase consistency; and to
- Get the data to appear (output) how we want.
Working with Strings
Whilst data like <:=$client.preferred_name:> may itself be stored as a string, we need to encapsulate it with the str class in order to manipulate it further. An example of this encapsulation is: <:=str($client.preferred_name):>
In both cases the preferred name will appear exactly the same but using str encapsulation will allow us to do more as discussed below.
Basic built in methods
|What it does
The first character of each word in a string will be capitalised.
Returns the entire string as in uppercase format.
Returns the string as all lower case.
Returns the first character only as capitalised, as opposed to title which will capitalise the first character of every word in a string: “MACQUARIE CASH FUND” would become “Macquarie cash fund”
Swaps the existing case of the string with the opposite (anything lower will become upper and vice versa)
eg ‘Sydney’ in swapcase would return as sYDNEY.
I cannot think of a time when I have ever used this but it could be a great trick if you want to bug your end users
Advanced built in methods
|What it does
Removes white space from both start and end (left and right) of a string.
Not as sexy as it sounds but straight forward; strip in its native form will simply remove any white space. If by chance you had data or a string stored as“102 Queen St “, strip would turn that into “102 Queen St” eliminating the white space we saw to the right of St. Not commonly needed as in most instances when you save data in Xplan it removes white spaces but there are instances where it doesn’t and this can come in handy for error redundancy.
|<:=$client.preferred_address.strip():><:if len(str($client.comments).strip()):>Yes comments exist <:end:>|
x here represents any leading characters you want to remove from the string.
Strip isn’t just used to remove white space, by defining characters within this method it will remove the leading character of that type.
A classic example of this is where a string field may have been used for entering a dollar amount. There are plenty of areas in xplan where numbers and amounts may be stored as string data, you can still convert it to a floating number and manipulate the amounts…BUT..the issue is where users might add a dollar sign to their data entry eg instead of just entering 500 the user enters: $500.00.This is problematic for your output as you might be using a static dollar sign so now you will get $$500.00 appearing. it will also cause any mathematical manipulation to fail. So strip provides the solution such as: <:=str(float($client.remuneration_amount)).strip(‘$’):>
Works the same as strip however it only removes leading characters from the left.
Commonly you may see this used with date coding for example. <:=datetime_merge.format(‘%d’):> would return a value of 03 if run on the third of January but chances are you just want your date to display as 3 January not 03.
Using the lstrip function will remove the first left 0
As above but looks for the leading characters from the right of the string.
Looks for and replaces one defined character with another. .replace(‘x’, ‘y’) where x = the character you want to find and y = the character to replace it with. To replace it with white space y can equal ‘ ‘ or to remove x entirely y can equal ”
A very handy method to keep in mind more so for data manipulation but at times can have uses for data output. This item will look for any character you define and replace it with whatever you specify. Common examples include manipulating dates.
For example the date may have been saved as ‘22/12/2014’ in order to use the date for a portfolio report or any comparison (eg comparing one date with another) you need to reduce it to the raw numbers.
|<:let mystring=’22/12/2014’:><:=str(mystring).replace(‘/’, ‘ ’):>|
Slicing syntax or literally slicing the string into its subparts (characters) can be useful for both data manipulation and data output.
As we mentioned at the start strings are made up of characters. So in the string ‘Gold Service’ we can see the characters of the string and also the position they occupy from the view of the system.
- You will notice that the first character takes the 0 position
- And that space counts as a character
So slicing works by taking the specified start and end positions you want
Note that the end point is the character where the slicing stops but doesn’t include the end character. The start character is always included and the end always excluded.
So for ‘Gold’ we would need [0:4] if we used [0:3] we would get ‘Gol’
Nnow that we know the positions of our string if we wanted to just extract the specific service standard we could use <:=str(myservice_benchmark)[0:4]:> and this would return ‘Gold’
Two of the most common times you may see slicing in action in Xmerge is for things like the first initial of a client name and or ABN output.
My client’s title, first name and last name is: Mr Sample Client.
But on my correspondence I want to show: Mr S. Client
I would use the following syntax: <:=$client.title:> <:=str($client.first_name)[0:1]:>. <:=$client.last_name:>
ABN data is another one where it may not be formatted correctly in many cases it may be stored as a whole number (integer) or a string without the formatting. So our ABN might be: 90111222333 and we want to show it as 90 111 222 333
It’s also worth noting that each position in our strings is a reference position or index. That means for single characters we don’t necessarily need to slice. Using our client first initial example, a more straight forward implementation we could use would be: <:=str($client.first_name):> and whilst unlikely (because its not automatically forced in Xplan) if we wanted to add some redundancy to ensure it always merges as a capital, we could do <:=str($client.first_name).upper():>
Other slicing bits
With my_string being equal to ‘Gold Service’
|<:=str(my_string)[5:]:>||Would return all characters after the first four. Gold Service would return ‘Service’|
|<=str(my_string)[-7:]:>||Would exclude the last seven characters and return ‘Gold’|
Conditioning and Operators
|What it does
Returns the length (len) of an object.
Short for length, it is used more than just with strings but you may see it often used around string and text items for conditioning. Unlike our positions or indexes, len counts the characters sequentially but does include white spaces so our ‘Gold Service’ string would return a len of 12
In is an operator that can be used to check if X exists (in) Y.
If x is found to exist in Y it returns a true value as the condition is met.
<:if ‘Balanced’ in str($client.risk_profile):><:end:> Checks to see if ‘Balanced’ is in the string that gets returned for the clients risk profile. If the clients right profile was ‘Balanced’ it will activate the condition, if the clients risk profile was ‘High Growth’ it would return false and the condition wouldn’t activate.
It’s important to be aware of the data you are trying to compare. This is true of all XMERGE but in the above example if our ‘Balanced’ risk profile was actually called “balanced” in lower case (in the system assumptions) it would return a false value, conversely if we used <:if ‘balanced’ in str($client.risk_profile):> and the actual client risk profile was ‘Balanaced’ the condition would fail.
So it’s important to always be comparing like data, for extra redundancy we might use: <:if ‘balanced’ in str($client.risk_profile).lower():>
|<:if ‘X’ in str(y):><:if ‘Balanced’ in str($client.risk_profile):>
<:if str($client.risk_profile) in [‘Balanced’]:>
Same as above but checks if X is not in Y
|<:if ‘Balanced’ not in str($client.risk_profile):>|
+ or concatenate is a way of adding strings together. Generally this is useful for when you are working with variables. For example, lets say we wanted to represent the clients full name, traditionally you would do this via calling <:=$client.first_name:> <:=$client.last_name:> but if for some reason you absolutely had to show that in one bit of code you could concatenate or add the strings like this: <:=str($client.first_name)+’ ‘+str($client.last_name):>
In the above you can see we have added (+) both a space between the first and last name as well as adding the last name, all in the one code call. In general though you are likely to use this more with variables such as below: <:let clientFullName=str($client.first_name)+’ ‘+str($client.last_name):> Whenever we call <:=clientFullName:> the output would return ‘Sample Client’ More on variables later though.
So hopefully you are now feeling excited…or looking forward..maybe just ready to tackle strings and getting the data and formatting you want in your xplan templates.
If you found this helpful or you have any follow up questions let us know below and stay tuned for future articles.
build a helpful, collaborative, innovative and beneficial community
For a long time now xplan development and coding has been the domain of mystics, those keepers of knowledge who magically make those templates and things in xplan work but who rarely explain the why and horde away knowledge like its some sort of lost treasure.
Simply put, you can’t build a helpful, collaborative, innovative and beneficial community for everyone, without those foundations of knowledge and access.