13.7. Text Functions

The following text functions are available for use in formulas in Cartographica. To use them, they must always be "attached" to a string object, as they are string object methods, as opposed to pure functions. Therefore, if you have a string column named my_value, you must use my_value.upper() to convert this to upper case. The length function, len(my_value), is a generic function and thus still must surround the string variable.

Also note that strings use collection operators as well, so if you want the first 2 characters of a string, you may retrieve them by using my_value[0:2]; similarly, the 3rd and 4th characters may be retrieved by using my_value[2:4]. In addition, negative numbers connote references from the end of the string, so my_value[-2:] would retrieve the last 2 characters at the end of the string (the lack of a number after the colon connotes until the end).

1.5 Change

	1.5 Change
For those who have used Text functions in the past, there was a change in version 1.5 and beyond because of the adoption of a new Python 3-based back-end. In Cartographica 1.5 and beyond, Text functions are object methods and not pure functions. This means that if you previously used `upper(my_value)` to convert my_value to uppercase, then you now must use `my_value.upper()`. Cartographica will present an error or warning if this change affects existing formulas.

For those who have used Text functions in the past, there was a change in version 1.5 and beyond because of the adoption of a new Python 3-based back-end. In Cartographica 1.5 and beyond, Text functions are object methods and not pure functions. This means that if you previously used upper(my_value) to convert my_value to uppercase, then you now must use my_value.upper(). Cartographica will present an error or warning if this change affects existing formulas.

str .capitalize( );

Returns text in title case. First letters of words are made upper case, with the remainder lower.
str .upper( );

Returns text in upper case.
str .lower( );

Returns text in lower case.
int .find( sub,
start,
end);
str sub;
int start;
int end;

Returns the location that the string sub is found within the string (starting at the beginning).
Optional parameters are start and end, the starting and ending locations of the search.
int .rfind( sub,
start,
end);
str sub;
int start;
int end;

Returns the location that the string sub is found within the string, starting at the end.
Optional parameters are start and end, the starting and ending locations of the search.
int .count( sub,
start,
end);
str sub;
int start;
int end;

Returns the count of the number of times that the string sub is found within the string.
Optional parameters are start and end, the starting and ending locations of the search.
int .split( sep,
maxsplit);
str sep;
int maxsplit;

Returns an array of text strings that are separated by the text string sep, optionally with a maximum number of splits, maxsplit. If the separator (sep) is omitted, the algorithm will use consecutive whitespace as the split.
'1,2,3,4'.split(',') returns ['1','2','3','4']
This method is especially useful for creating new columns out of columns that may have been strings with multiple values previously. For example, let's say you have a column for the City, State of an address named CITYSTATE and containing Washington, DC for example. By creating two new columns and using these formulas respectively:
City: CITYSTATE.split(',')[0].trim()
State: CITYSTATE.split(',')[1].trim()
you will get the City in one column and the State in the next.
Note that we use the 1st array element for the first and the 2nd array element for the second, since array elements start with 0, not 1.
int .join( array);
[str] array;

Returns a new string created by joining the elements of the string array by the string that the method is executing on. This can be used in interesting ways to join values from other columns. For example, given columns A, B, C and D, you can join them by hyphens by doing the following:
```
'-'.join([A,B,C,D])
```
in the above, we created an ad hoc array by putting the individual values between square brackets and separated by commas.
int .strip( stripchars);
str stripchars;

Returns a new text string with the trailing and leading whitespace removed. If you pass a string in stripchars, the method will remove those characters (instead of whitespace) from the leading and trailing positions.
int .rstrip( stripchars);
str stripchars;

Returns a new text string with the trailing whitespace removed. If you pass a string in stripchars, the method will remove those characters (instead of whitespace) from the trailing positions.
int .lstrip( stripchars);
str stripchars;

Returns a new text string with the leading whitespace removed. If you pass a string in stripchars, the method will remove those characters (instead of whitespace) from the leading positions.


	Note that we use the 1st array element for the first and the 2nd array element for the second, since array elements start with 0, not 1.


	in the above, we created an ad hoc array by putting the individual values between square brackets and separated by commas.

`int .find(`	`sub`,
	`start`,
	`end)`;

`int .rfind(`	`sub`,
	`start`,
	`end)`;

`int .count(`	`sub`,
	`start`,
	`end)`;

`int .split(`	`sep`,
	`maxsplit)`;