Recipe 5.18. Inserting a Line

Problem

You want to insert a complete line of text in a string that contains multiple lines separated by newlines. The desired insertion point is after the nth line.

Solution

Sample code folder: Chapter 05\InsertLine

Split the string into a string array using the newlines as the split point, append the line to be inserted to the nth string, and use Join() to glue the string back together again.

Discussion

Use the string function Split(), which is not to be confused with the String.Split() method, to split the string into a string array. The Split() method splits the string at individual-character split points, but the Split() function lets you split the string using a multicharacter string for the defined split point. The vbNewLine constant is actually a two-character string, so you must use the Split() function to avoid splitting on the carriage-return character only, leaving the line-feed character at the front end of each array string.

Rather than redimensioning the string array to shuffle the lines and create a slot in which to insert the new one, it's easier to just concatenate the new string, accompanied by a newline constant, to the appropriate string in the array. This is a simpler and more efficient procedure that involves less shuffling of string data in memory, and the results after doing a Join() are identical.

This insert functionality works well as a standalone function, which is presented in the following lines of code:

 Public Function InsertLine(ByVal source As String, _       ByVal lineNum As Integer, _       ByVal lineToInsert As String) As String    ' ----- Insert a line in the middle of a set of lines.    Dim lineSet( ) As String    Dim atLine As Integer    ' ----- Break the content into multiple lines.    lineSet = Split(source, vbNewLine)        ' ----- Determine the new location, being careful not    '       to fall off the edge of the line set.    atLine = lineNum    If (atLine < 0) Then atLine = 0    If (atLine >= lineSet.Length) Then       ' ----- Append to the end of everything.       lineSet(lineSet.Length - 1) &= vbNewLine & lineToInsert    Else       ' ----- Insert before the specified line.       lineSet(atLine) = _          lineToInsert & vbNewLine & lineSet(atLine)    End If    ' ----- Reconnect and return the parts.    Return Join(lineSet, vbNewLine) End Function 

The string is first split at line boundaries into a string array. LineNum is the number of the line after which the lineToInsert string is inserted. You can pass zero to this parameter to insert the new line before the first one. After appending the new string to the appropriate string in the array, along with a vbNewLine to separate it from the original line, the array is glued back together with the Join() function, using a vbNewLine between each line to restore its original structure. This new string is then returned as the result of the InsertLine() function.

The following lines of code demonstrate the function's use:

 Dim result As New System.Text.StringBuilder result.AppendLine("This string") result.AppendLine("contains") result.AppendLine("several") result.AppendLine("lines") result.Append("of text.") ' ----- Show the original content. Dim resultAsString As String = result.ToString( ) MsgBox(resultAsString) ' ----- Show the modified content. resultAsString = InsertLine(resultAsString, 3, "(inserted)") MsgBox(resultAsString) 

A StringBuilder is used to build the original string containing several lines of text separated by vbNewLines. The first message box (displayed in Figure 5-18) shows the string before the extra line is inserted. The second message box (displayed in Figure 5-19) shows the new string inserted after the third line.

Figure 5-18. The original string containing five lines of text

The Split() method will accept either a character or a string to define the split points in a string, but only the first character of the string is used. The Split() function, however, uses the entire string parameter, of any length, to split the string. Both the Split() method and the Split() function are very handy, but make sure you understand the difference in the way they work.

Figure 5-19. The same string after "(inserted)" is inserted after the third line

See Also

Recipe 5.17 also discusses text insertions. The difference between the Split() method and the Split() function is further discussed in Recipe 5.44.