gtk.TextIter.get_buffer

    def get_buffer()

The get_buffer() method returns the gtk.TextBuffer object this iterator is associated with.

gtk.TextIter.copy

    def copy()

The copy() method creates a copy of the textiter.

gtk.TextIter.get_offset

    def get_offset()

The get_offset() method returns the character offset of the textiter. Each character in a gtk.TextBuffer has an offset, starting with 0 for the first character in the textbuffer. Use gtk.TextBuffer.get_iter_at_offset() to convert an offset back into a textiter.

gtk.TextIter.get_line

    def get_line()

The get_line() method returns the line number containing the textiter. Lines in a gtk.TextBuffer are numbered beginning with 0 for the first line.

gtk.TextIter.get_line_offset

    def get_line_offset()

The get_line_offset() method returns the character offset of the textiter location, counting from the start of the line containing the textiter location. The first character on the line has offset 0.

gtk.TextIter.get_line_index

    def get_line_index()

The get_line_offset() method returns the byte index of the textiter location, counting from the start of the line containing the textiter location. Remember that gtk.TextBuffer encodes text in UTF-8, and that characters can require a variable number of bytes to represent.

gtk.TextIter.get_visible_line_offset

    def get_visible_line_offset()

The get_visible_line_offset() method returns the offset in characters of the textiter location from the start of the line containing the textiter location, not counting characters that are invisible due to tags with the "invisible" attribute set.

gtk.TextIter.get_visible_line_index

    def get_visible_line_index()

The get_visible_line_index() method returns the byte index of the textiter location from the start of the line, not counting bytes that are invisible due to tags with the "invisible" attribute set.

gtk.TextIter.get_char

    def get_char()

The get_char() method returns the Unicode character at this textiter location. If the textiter points at a non-character element, such as an image embedded in the buffer, the Unicode "unknown" character 0xFFFC is returned. If invoked on the end textiter, the null character is returned; \0 is not a valid Unicode character. So you can write a loop which ends when the get_char() method returns \0.

gtk.TextIter.get_slice

    def get_slice(end)

The get_slice() method returns the text in the range between the locations specified by the textiter and end. A "slice" is an array of characters encoded in UTF-8 format, including the Unicode "unknown" character 0xFFFC for iterable non-character elements in the textbuffer, such as images. Because images are encoded in the slice, byte and character offsets in the returned array will correspond to byte offsets in the textbuffer. Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a pixbuf or widget is in the textbuffer.

gtk.TextIter.get_text

    def get_text(end)

The get_text() method returns the text in the range between the locations specified by the textiter and end. If the range contains non-text elements such as images, the character and byte offsets in the returned string will not correspond to character and byte offsets in the textbuffer. If you want the offsets to correspond, use the get_slice() method.

gtk.TextIter.get_visible_slice

    def get_visible_slice(end)

The get_visible_slice() method is similar to the get_slice() method, but invisible text is excluded. Invisible text is text with the "invisible" attribute set on it.

gtk.TextIter.get_visible_text

    def get_visible_text(end)

The get_visible_text() method is similar to the get_text(), but invisible text is excluded. Invisible text is text with the "invisible" attribute set on it.

gtk.TextIter.get_pixbuf

    def get_pixbuf()

The get_pixbuf() method returns the gtk.gdk.Pixbuf object at the textiter location, if any; otherwise, None is returned.

gtk.TextIter.get_marks

    def get_marks()

The get_marks() method returns a list of all gtk.TextMark objects at the textiter location. Because marks don't take up any "space" in the buffer, multiple marks can exist in the same location. The returned list is not in any meaningful order.

gtk.TextIter.get_child_anchor

    def get_child_anchor()

The get_child_anchor() method returns the gtk.TextChildAnchor at the textiter location, if any; otherwise, None is returned.

gtk.TextIter.get_toggled_tags

    def get_toggled_tags(toggled_on)

The get_toggled_tags() method returns a list of gtk.TextTag objects that are toggled on or off at this point. If toggled_on is True, the list contains tags that are toggled on. If a tag is toggled on at the textiter location, some non-empty range of characters following the textiter has that tag applied to it. If a tag is toggled off, then some non-empty range following the textiter location does not have the tag applied to it.

gtk.TextIter.begins_tag

    def begins_tag(tag=None)

The begins_tag() method returns True if tag is toggled on at exactly this point. If tag is None, this method returns True if any tag is toggled on at this point. Note that the begins_tag() method returns True only if the textiter location is the start of the tagged range; the has_tag() indicates if a textiter location is within a tagged range.

gtk.TextIter.ends_tag

    def ends_tag(tag=None)

The ends_tag() method returns True if tag is toggled off at the location the textiter points to. If tag is None, this method returns True if any tag is toggled off at this point. Note that the ends_tag() returns True only if the textiter location is the end of the tagged range; the has_tag() indicates if a textiter location is within a tagged range.

gtk.TextIter.toggles_tag

    def toggles_tag(tag=None)

The toggles_tag() method returns True if a range of text with tag applied to it begins or ends at the textiter location. If tag is None this method returns True if any tag begins or ends at the textiter location.

gtk.TextIter.has_tag

    def has_tag(tag)

The has_tag() method returns True if the textiter location is within a range of text tagged with tag.

gtk.TextIter.get_tags

    def get_tags()

The get_tags() method returns a list of tags that apply to the textiter location, in ascending order of priority (highest-priority tags are last).

gtk.TextIter.editable

    def editable(default_setting)

The editable() method returns True if the character at the textiter location is within an editable range of text. Non-editable text is "locked" and can't be changed by the user via a gtk.TextView. This method is a convenience wrapper around the get_attributes() method. If no tags applied to this text location affect editability, the value of default_setting will be returned.

Do not use this method to determine if text can be inserted at the textiter location. For insertion you don't want to know if the char at the textiter location is inside an editable range of text, you want to know whether a new character inserted at the textiter location would be inside an editable range of text. Use the can_insert() method to determine if text can be inserted.

gtk.TextIter.can_insert

    def can_insert(default_editability)

The can_insert() method considers the default editability of the buffer, and the tags that affect editability, to determine if text inserted at the textiter location would be editable. If so, the user should be allowed to insert text at the textiter location. The gtk.TextBuffer.insert_interactive() uses this function to determine if insertions are allowed at a given position.

gtk.TextIter.starts_word

    def starts_word()

The starts_word() method returns True if the textiter location begins a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

gtk.TextIter.ends_word

    def ends_word()

The ends_word() method returns True if the textiter location ends a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

gtk.TextIter.inside_word

    def inside_word()

The inside_word() method returns True if the textiter location is inside a natural-language word (as opposed to say inside some whitespace). Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

gtk.TextIter.starts_sentence

    def starts_sentence()

The starts_sentence() method returns True if the textiter location begins a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms).

gtk.TextIter.ends_sentence

    def ends_sentence()

The ends_sentence() method returns True if the textiter location ends a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms).

gtk.TextIter.inside_sentence

    def inside_sentence()

The inside_sentence() method returns True if the textiter location is inside a sentence (as opposed to in between two sentences, e.g. after a period and before the first letter of the next sentence). Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms).

gtk.TextIter.starts_line

    def starts_line()

The starts_line() method returns True if the textiter location begins a paragraph, i.e. if the .get_line_offset() method would return 0.

gtk.TextIter.ends_line

    def ends_line()

The ends_line() method returns True if the textiter location points to the start of the paragraph delimiter characters for a line (delimiters will be either a newline, a carriage return, a carriage return followed by a newline, or a Unicode paragraph separator character). Note that an textiter pointing to the \n of a \r\n pair will not be counted as the end of a line, the line ends before the \r. The end textiter is considered to be at the end of a line, even though there are no paragraph delimiter chars there.

gtk.TextIter.is_cursor_position

    def is_cursor_position()

The is_cursor_position() method returns True if the cursor can be placed at the textiter location. See the forward_cursor_position() method for details on what a cursor position is.

gtk.TextIter.get_chars_in_line

    def get_chars_in_line()

The get_chars_in_line() method returns the number of characters in the line containing the textiter location, including the paragraph delimiters.

gtk.TextIter.get_bytes_in_line

    def get_bytes_in_line()

The get_bytes_in_line() method returns the number of bytes in the line containing the textiter location, including the paragraph delimiters.

gtk.TextIter.get_attributes

    def get_attributes(values)

The get_attributes() method computes the effect of any tags applied to the textiter location and applies those attributes to the gtk.TextAttributes object specified by values (which should be initialized to the default settings you wish to use if no tags are in effect). Typically the default attributes are obtained from the gtk.TextView.get_default_attributes() method. If any tags affected values, the method returns True.

gtk.TextIter.get_language

    def get_language()

The get_language() method is a convenience wrapper around the get_attributes() method, that returns the language in effect at the textiter location. If no tags affecting language apply to the textiter location, the return value is identical to that of the gtk.get_default_language() function.

gtk.TextIter.is_end

    def is_end()

The is_end() method returns True if the textiter is the end textiter, i.e. one past the last dereferenceable textiter in the buffer. The is_end() method is the most efficient way to check whether an textiter is the end textiter.

gtk.TextIter.is_start

    def is_start()

The is_start() method returns True if the textiter location is at the start of the textbuffer, that is if the textiter location has a character offset of 0.

gtk.TextIter.forward_char

    def forward_char()

The forward_char() method moves the textiter location forward by one character offset and returns True if the textiter location moved and the new location is dereferenceable. Note that images embedded in the buffer occupy 1 character slot, so the forward_char() method may actually move onto an image instead of a character, if you have images in your buffer. If the textiter location is the end textiter or one character before it, the textiter location will now point at the end textiter, and the forward_char() method returns False.

gtk.TextIter.backward_char

    def backward_char()

The backward_char() method moves the textiter location backward by one character offset and returns True if the textiter location moved. If the old textiter location was the first in the buffer (character offset 0), the backward_char() method returns False.

gtk.TextIter.forward_chars

    def forward_chars(count)

The forward_chars() method moves the textiter location forward count characters if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The forward_chars() method returns True if the new position of the resulting textiter location is different from its original position, and is dereferenceable (the last textiter in the buffer is not dereferenceable). If count is 0, the function does nothing and returns False.

gtk.TextIter.backward_chars

    def backward_chars(count)

The backward_chars() method moves the textiter location backward forward count characters, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The backward_chars() method returns True if the new position of the resulting textiter location is different from its original position, and is dereferenceable (the last textiter in the buffer is not dereferenceable). If count is 0, the function does nothing and returns False.

gtk.TextIter.forward_line

    def forward_line()

The forward_line() method moves the textiter location to the start of the next line and returns True if the textiter location moved to a dereferenceable position, and False if the textiter location moved to the end of the buffer, or if the textiter location was originally at the end of the buffer.

gtk.TextIter.backward_line

    def backward_line()

The backward_line() method moves the textiter location to the start of the previous line and returns True if the textiter location was moved. If the textiter location was at the textbuffer start, this method returns False. For example if the textiter location was already on line 0, but not at the start of the line, the textiter location is snapped to the start of the line and the method returns True.

gtk.TextIter.forward_lines

    def forward_lines(count)

The forward_lines() method moves the textiter location forward count lines, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The method returns:

If count is negative, the textiter location moves backward by count lines.

gtk.TextIter.backward_lines

    def backward_lines(count)

The backward_lines() method moves the textiter location backward by count lines, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The method returns:

If count is negative, the textiter location moves forward by count lines.

gtk.TextIter.forward_word_ends

    def forward_word_ends(count)

The forward_word_ends() method calls the forward_word_end() method up to count times or the backward_word_starts() method if count is negative. The method returns True if the textiter location changed and the resulting location is not at the end of the textbuffer.

gtk.TextIter.backward_word_starts

    def backward_word_starts(count)

The backward_word_starts() method calls the backward_word_start() method up to count times or the forward_word_ends() method if count is negative. The method returns True if the textiter location changed and the resulting location is not at the end of the textbuffer.

gtk.TextIter.forward_word_end

    def forward_word_end()

The forward_word_end() method moves the textiter location forward to the next word end. If the textiter location is currently on a word end, the location moves forward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). The method returns True if the textiter location moved to a dereferenceable position

gtk.TextIter.backward_word_start

    def backward_word_start()

The backward_word_start() method moves the textiter location backward to the previous word start. If the textiter location is currently on a word start, the location moves backward to the next one before that. Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms). The method returns True if the textiter location moved.

gtk.TextIter.forward_cursor_position

    def forward_cursor_position()

The forward_cursor_position() method moves the textiter location forward by a single cursor position. Cursor positions are (unsurprisingly) positions where the cursor can appear. Surprisingly, there may not be a cursor position between all characters. The most common example for European languages would be a carriage return/newline sequence. For some Unicode characters, the equivalent of say the letter "a" with an accent mark will be represented as two characters, first the letter then a "combining mark" that causes the accent to be rendered; so the cursor can't go between those two characters. The method returns True if the textiter location changed and the resulting location is not at the end of the textbuffer.

gtk.TextIter.backward_cursor_position

    def backward_cursor_position()

The backward_cursor_position() method is similar to the forward_cursor_position() method, except the location moves backward.

gtk.TextIter.forward_cursor_positions

    def forward_cursor_positions(count)

The forward_cursor_positions() method moves up to count cursor positions. See the forward_cursor_position() method for more details. The method returns True if the textiter moved to a dereferenceable location.

gtk.TextIter.backward_cursor_positions

    def backward_cursor_positions(count)

The backward_cursor_positions() method moves the textiter location up to count cursor positions. See the forward_cursor_position() method for details.

gtk.TextIter.backward_sentence_start

    def backward_sentence_start()

The backward_sentence_start() method moves the textiter location backward to the previous sentence start. If the textiter location is already at the start of a sentence, the location moves backward to the next one. Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms).

gtk.TextIter.forward_sentence_end

    def forward_sentence_end()

The forward_sentence_end() method moves the textiter location forward to the next sentence end. (If the textiter location is at the end of a sentence, the location moves to the next end of sentence.) Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary algorithms). The method returns True if the textiter location changed and the resulting location is not at the end of the textbuffer.

gtk.TextIter.backward_sentence_starts

    def backward_sentence_starts(count)

The backward_sentence_starts() method calls the backward_sentence_start() method (or the forward_sentence_end()() method if count is negative) up to count times, or until it returns False. If count is negative, the location moves forward instead of backward. The method returns True if the textiter location changed and the resulting location is not at the end of the textbuffer.

gtk.TextIter.forward_sentence_ends

    def forward_sentence_ends(count)

The forward_sentence_ends() method calls the forward_sentence_end() method count times (or until the forward_sentence_end() method returns False). If count is negative, the location moves backward instead of forward. The method returns True if the textiter location changed and the resulting location is not at the end of the textbuffer.

gtk.TextIter.forward_visible_word_ends

    def forward_visible_word_ends(count)

The forward_visible_word_ends() method calls the forward_visible_word_end() method the number of times specified by count.

gtk.TextIter.backward_visible_word_starts

    def backward_visible_word_starts(count)

The backward_visible_word_starts() method calls the backward_visible_word_start() method the number of times specified by count.

gtk.TextIter.forward_visible_word_end

    def forward_visible_word_end()

The forward_visible_word_end() method moves the textiter forward to the next visible word end. (If the textiter is currently on a word end, it moves forward to the next one after that.) Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

gtk.TextIter.backward_visible_word_start

    def backward_visible_word_start()

The backward_visible_word_start() method moves the textiter backward to the previous visible word start. (If textiter is currently on a word start, it moves backward to the next one after that.) Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word break algorithms).

gtk.TextIter.forward_visible_cursor_position

    def forward_visible_cursor_position()

The forward_visible_cursor_position() method moves the textiter location forward by a single visible cursor position. Cursor positions are (unsurprisingly) positions where the cursor can appear. Surprisingly, there may not be a cursor position between all characters. The most common example for European languages would be a carriage return/newline sequence. For some Unicode characters, the equivalent of say the letter "a" with an accent mark will be represented as two characters, first the letter then a "combining mark" that causes the accent to be rendered; so the cursor can't go between those two characters. The method returns True if the textiter location changed and the resulting location is not at the end of the textbuffer.

gtk.TextIter.backward_visible_cursor_position

    def backward_visible_cursor_position()

The backward_visible_cursor_position() method is similar to the forward_visible_cursor_position() method, except the location moves backward.

gtk.TextIter.forward_visible_cursor_positions

    def forward_visible_cursor_positions(count)

The forward_visible_cursor_positions() method moves up to count visible cursor positions. See the forward_visible_cursor_position() method for more details. The method returns True if the textiter moved to a dereferenceable location.

gtk.TextIter.backward_visible_cursor_positions

    def backward_visible_cursor_positions(count)

The backward_visible_cursor_positions() method moves the textiter location up to count visible cursor positions. See the forward_visible_cursor_position() method for details.

gtk.TextIter.forward_visible_line

    def forward_visible_line()

The forward_visible_line() method moves the textiter location to the start of the next visible line and returns True if the textiter location moved to a dereferenceable position, and False if the textiter location moved to the end of the buffer, or if the textiter location was originally at the end of the buffer.

gtk.TextIter.backward_visible_line

    def backward_visible_line()

The backward_visible_line() method moves the textiter location to the start of the previous visible line and returns True if the textiter location was moved. If the textiter location was at the textbuffer start, this method returns False. For example if the textiter location was already on line 0, but not at the start of the line, the textiter location is snapped to the start of the line and the method returns True.

gtk.TextIter.forward_visible_lines

    def forward_visible_lines(count)

The forward_visible_lines() method moves the textiter location forward count visible lines, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The method returns:

If count is negative, the textiter location moves backward by count visible lines.

gtk.TextIter.backward_visible_lines

    def backward_visible_lines(count)

The backward_visible_lines() method moves the textiter location backward by count lines, if possible. If the textiter location would move past the start or end of the buffer, the location moves to the start or end of the textbuffer. The method returns:

If count is negative, the textiter location moves forward by count visible lines.

gtk.TextIter.set_offset

    def set_offset(char_offset)

The set_offset() method sets the textiter location to point to the location that is char_offset counts from the start of the textbuffer (starting with 0).

gtk.TextIter.set_line

    def set_line(line_number)

The set_line() method sets the textiter location to the start of the line specified by line_number. If line_number is negative or larger than the number of lines in the textbuffer, the method moves the textiter location to the start of the last line in the buffer.

gtk.TextIter.set_line_offset

    def set_line_offset(char_on_line)

The set_line_offset() method moves the textiter location within a line, to the new character (not byte) offset specified by char_on_line. The character offset must be less than or equal to the number of characters in the line; if equal, the textiter location moves to the start of the next line. See the set_line_index() method if you have a byte index rather than a character offset.

gtk.TextIter.set_line_index

    def set_line_index(byte_on_line)

The set_line_index() method is similar to the set_line_offset(), but works with a byte index instead of a character index. The given byte index must be at the start of a character, it can't be in the middle of a UTF-8 encoded character.

gtk.TextIter.forward_to_end

    def forward_to_end()

The forward_to_end() method moves the textiter location forward to the "end textiter," that points one past the last valid character in the buffer. The get_char() method called on the end textiter returns 0, which is convenient for writing loops.

gtk.TextIter.forward_to_line_end

    def forward_to_line_end()

The forward_to_line_end() method moves the textiter to point to the paragraph delimiter characters at the end of the current line. The paragraph delimiter characters are a newline, a carriage return, a carriage return-newline in sequence, or the Unicode paragraph separator character. If the textiter is already at the paragraph delimiter characters, moves to the paragraph delimiter characters for the next line. If the textiter location is on the last line in the buffer, which does not end in paragraph delimiters, moves to the end textiter (end of the last line), and returns False.

gtk.TextIter.set_visible_line_offset

    def set_visible_line_offset(char_on_line)

The set_visible_char_offset() method is similar to the set_line_offset() method, but the offset is in visible characters, i.e. text with the invisible attribute set is not counted in the offset.

gtk.TextIter.set_visible_line_index

    def set_visible_line_index(byte_on_line)

The set_visible_line_index() method is similar to the set_line_index() method, but the index is in visible bytes, i.e. text with the attribute set is not counted in the index.

gtk.TextIter.forward_to_tag_toggle

    def forward_to_tag_toggle(tag)

The forward_to_tag_toggle() method moves the textiter location forward to the next toggle (on or off) of the gtk.TextTag specified by tag, or to the next toggle of any tag if tag is None. If no matching tag toggles are found, this method returns False and sets the textiter location to the end of the textbuffer; otherwise, returns True. The forward_to_tag_toggle() method does not recognize toggles located at the textiter location, only toggles after the textiter location.

gtk.TextIter.backward_to_tag_toggle

    def backward_to_tag_toggle(tag)

The backward_to_tag_toggle() method moves the textiter location backward to the next toggle (on or off) of the gtk.TextTag specified by tag, or to the next toggle of any tag if tag is None. If no matching tag toggles are found, this method returns False and sets the textiter location to the start of the textbuffer; otherwise, returns True. The backward_to_tag_toggle() method does not recognize toggles located at the textiter location, only toggles before the textiter location.

gtk.TextIter.forward_find_char

    def forward_find_char(pred, user_data, limit)

The forward_find_char() method advances the textiter, calling the function specified by pred on each character. If pred returns True, forward_find_char stops scanning and returns True. If pred never returns True, the textiter location is set to limit or the end textiter, if limit is None.

gtk.TextIter.backward_find_char

    def backward_find_char(pred, user_data, limit)

The backward_find_char() method is similar to the forward_find_char() method, but goes backward from the textiter location.

gtk.TextIter.forward_search

    def forward_search(str, flags, limit=None)

The forward_search() method searches forward for the text string specified by str and returns a tuple containing gtk.TextIter objects that point at the start and end locations of the match. The search will stop at the location specified by limit or the end of the textbuffer if limit is None or is not specified. Note that a search is a linear or O(n) operation, so you may wish to use limit to avoid locking up your UI when searching large buffers.

If the gtk.TEXT_SEARCH_VISIBLE_ONLY flag is present, the match may have invisible text interspersed in str (i.e. str will be a possibly-noncontiguous subsequence of the matched range). Likewise, if gtk.TEXT_SEARCH_TEXT_ONLY is present, the match may have pixbufs or child anchors mixed inside the matched range. If these flags are not given, the match must be exact i.e. the special 0xFFFC character in str will match embedded pixbufs or child widgets.

gtk.TextIter.backward_search

    def backward_search(str, flags, limit=None)

The backward_search() method is the same as the forward_search() method, except searches backward.

gtk.TextIter.equal

    def equal(rhs)

The equal() method tests if the textiter specified by rhs points to the same location in the textbuffer as the textiter.

gtk.TextIter.compare

    def compare(rhs)

The compare() method returns:

Ordering is in character offset order, i.e. the first character in the buffer is less than the second character in the buffer.

gtk.TextIter.in_range

    def in_range(start, end)

The in_range() method returns True if the textiter location is in the text range specified by the gtk.TextIter objects start and end. start and end must be in ascending order.

gtk.TextIter.order

    def order(second)

The order() method swaps the locations of first and second if second comes before first in the buffer. This method can be used to ensure that first and second are in sequence. Most text buffer methods that take a range call this automatically, so there's no real reason to call it yourself in those cases. There are some exceptions, such as the in_range(), that expect a pre-sorted range.