poplines()

Return the specified number of lines from the beginning of a variable.

Syntax

poplines(text_variable, num_lines, [w])

Parameter

Parameter	Definition
text_variable	variable to be edited by poplines() This parameter must be a variable. You cannot use a string because poplines() edits the content of the variable.
num_lines	number of lines to be returned by this function
w	optional flag that removes all trailing whitespace from the text returned by poplines()

Description

The poplines() function returns the specified number of lines from the beginning of the user-defined variable, and it deletes these lines from the variable.

This function returns NULL when it encounters an error. Use the following values for the errno variable to troubleshoot poplines().

errno Value	Description of Failure
0	No error if poplines() returns NULL and errno equals zero, text_variable probably contains only white space that gets removed because of the w flag
68	E_PSL_EDOM text_variable is NULL
96	E_PSL_BAD_FUNCTION_PARAMETER text_variable is not a variable, num_lines is not a number, or num_lines is less than 1

Example

The following example demonstrates the poplines() function.

errno=0;
text_var=" Line 1\n Line 2\n Line 3\n Line 4";
print("Before poplines, text_var=".text_var);
result_text=poplines(text_var, 3);
print("\n\nAfter poplines, text_var=".text_var);
print("\n\nThe following lines were removed:\n". result_text);

The following output results from the preceding code.

Before poplines, text_var= Line 1
Line 2
Line 3
Line 4
After poplines, text_var= Line 4
The following lines were removed:
Line 1
Line 2
Line 3