Inserting some text before each line in a field
In this lesson we will see how to add a prefix at the start of each line in a piece of text.
The prefixed function
The prefixed function takes 2 parameters, a piece of text, pText, and a prefix, pPrefix. The function adds the prefix to each line of the text and returns the resulting text.
get prefixed(field "List",">")
put prefixed(the filenames of me,currentPath) into tFileList
prefixed function adds a prefix to the beginning of each line in a list of lines. It does this by using a repeat loop to build the new list (with prefixes), then returns that new list.
Because the new list is built by adding each line followed by a return character to the end, the final list contains an extra return character. To remove this, the function returns char 1 to -2 of the new list. In other words, it returns the new list from the first character to the second-to-last character, leaving out the final character which is the extra return.
One interesting thing about this function is that it doesn't require parameter error-checking: calling it with no parameters or with a single parameter does not cause a script error, and still returns something sensible. This is because if a parameter is missing, LiveCode treats it as the empty constant.
Suppose you call this function with a single parameter, like this:
put prefixed(someLines) into field "Prefixed Lines"
When the function is executed, the pPrefix parameter is treated as empty, since you didn't pass a second parameter. That means that the repeat loop simply adds each line in the pText parameter to the new list.
What happens if you don't provide any parameters at all? In this case, the pText parameter is treated as empty, so the repeat loop never executes. In this case, the new list is never built, and the function simply returns empty.
It's important to realize that you can't count on functions being "self-healing" like this. This particular function uses simple strings, they aren't required to be in a particular format, and the parameters don't include numbers or dates, and it happens to use them in ways that still work if one or both parameters is empty. But with many custom functions, an empty parameter or one that's in the wrong format can cause an execution error. To prevent this, most functions need to be written to check their parameters, and either substitute an appropriate default value or return an error message if a parameter is missing.
The prefixed function code
put prefixed(field "List",field "Prefix") into field "List"
function prefixed pText, pPrefix
repeat for each line tLine in pText
put pPrefix & tLine & return after tNewList
return char 1 to -2 of tNewList
A note on efficiency
The repeat loop in this function can also be written using the repeat with form:
repeat with x = 1 to the number of lines of pText
put pPrefix before line x of pText
This form has one advantage, which is that it doesn't need to create a new variable to hold the prefixed list. Instead, it adds the prefixes to the parameter variable itself. This saves the memory space needed for the duplicate list. However, this method is much slower than the repeat for each line form. The longer the list of lines, the more marked the speed difference becomes. In general, the speed difference more than makes up for the extra amount of memory used, particularly since the memory is only in use while the function is actually executing.