textiter: add starts_tag() and deprecate begins_tag()

The name gtk_text_*_begins_* was used only for begins_tag(). All other
similar functions use "starts": starts_line(), starts_word(), etc.

So for consistency, add gtk_text_iter_starts_tag() and deprecate
gtk_text_iter_begins_tag().

Also change (allow-none) to (nullable), to use the new annotation.

https://bugzilla.gnome.org/show_bug.cgi?id=759092

docs/reference/gtk/gtk3-sections.txt

@@ -3742,6 +3742,7 @@ gtk_text_iter_get_pixbuf
 gtk_text_iter_get_marks
 gtk_text_iter_get_toggled_tags
 gtk_text_iter_get_child_anchor
+gtk_text_iter_starts_tag
 gtk_text_iter_begins_tag
 gtk_text_iter_ends_tag
 gtk_text_iter_toggles_tag

gtk/gtktextiter.c

@@ -1153,25 +1153,26 @@ gtk_text_iter_get_toggled_tags  (const GtkTextIter  *iter,
 }
 
 /**
- * gtk_text_iter_begins_tag:
+ * gtk_text_iter_starts_tag:
  * @iter: an iterator
- * @tag: (allow-none): a #GtkTextTag, or %NULL
+ * @tag: (nullable): a #GtkTextTag, or %NULL
  *
  * Returns %TRUE if @tag is toggled on at exactly this point. If @tag
  * is %NULL, returns %TRUE if any tag is toggled on at this point.
  *
- * Note that if gtk_text_iter_begins_tag() returns %TRUE, it means that @iter is
+ * Note that if gtk_text_iter_starts_tag() returns %TRUE, it means that @iter is
  * at the beginning of the tagged range, and that the
  * character at @iter is inside the tagged range. In other
- * words, unlike gtk_text_iter_ends_tag(), if gtk_text_iter_begins_tag() returns
+ * words, unlike gtk_text_iter_ends_tag(), if gtk_text_iter_starts_tag() returns
  * %TRUE, gtk_text_iter_has_tag() will also return %TRUE for the same
  * parameters.
  *
  * Returns: whether @iter is the start of a range tagged with @tag
+ * Since: 3.20
  **/
 gboolean
-gtk_text_iter_begins_tag    (const GtkTextIter  *iter,
+gtk_text_iter_starts_tag (const GtkTextIter *iter,
-                             GtkTextTag         *tag)
+                          GtkTextTag        *tag)
 {
   GtkTextRealIter *real;
   GtkTextLineSegment *seg;
@@ -1201,6 +1202,31 @@ gtk_text_iter_begins_tag    (const GtkTextIter  *iter,
   return FALSE;
 }
 
+/**
+ * gtk_text_iter_begins_tag:
+ * @iter: an iterator
+ * @tag: (nullable): a #GtkTextTag, or %NULL
+ *
+ * Returns %TRUE if @tag is toggled on at exactly this point. If @tag
+ * is %NULL, returns %TRUE if any tag is toggled on at this point.
+ *
+ * Note that if gtk_text_iter_begins_tag() returns %TRUE, it means that @iter is
+ * at the beginning of the tagged range, and that the
+ * character at @iter is inside the tagged range. In other
+ * words, unlike gtk_text_iter_ends_tag(), if gtk_text_iter_begins_tag() returns
+ * %TRUE, gtk_text_iter_has_tag() will also return %TRUE for the same
+ * parameters.
+ *
+ * Returns: whether @iter is the start of a range tagged with @tag
+ * Deprecated: 3.20: Use gtk_text_iter_starts_tag() instead.
+ **/
+gboolean
+gtk_text_iter_begins_tag (const GtkTextIter *iter,
+                          GtkTextTag        *tag)
+{
+  return gtk_text_iter_starts_tag (iter, tag);
+}
+
 /**
  * gtk_text_iter_ends_tag:
  * @iter: an iterator

gtk/gtktextiter.h

@@ -170,7 +170,11 @@ GDK_AVAILABLE_IN_ALL
 GSList  *gtk_text_iter_get_toggled_tags  (const GtkTextIter  *iter,
                                           gboolean            toggled_on);
 
-GDK_AVAILABLE_IN_ALL
+GDK_AVAILABLE_IN_3_20
+gboolean gtk_text_iter_starts_tag        (const GtkTextIter  *iter,
+                                          GtkTextTag         *tag);
+
+GDK_DEPRECATED_IN_3_20_FOR(gtk_text_iter_starts_tag)
 gboolean gtk_text_iter_begins_tag        (const GtkTextIter  *iter,
                                           GtkTextTag         *tag);