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

3 files changed, 38 insertions, 7 deletions

diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index cb13a99e7c..e5cd1ef7e7 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/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
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 2496ea85bc..c806237a58 100644
--- a/gtk/gtktextiter.c
+++ b/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,
-                             GtkTextTag         *tag)
+gtk_text_iter_starts_tag (const GtkTextIter *iter,
+                          GtkTextTag        *tag)
 {
   GtkTextRealIter *real;
   GtkTextLineSegment *seg;
@@ -1202,6 +1203,31 @@ gtk_text_iter_begins_tag    (const GtkTextIter  *iter,
 }
 
 /**
+ * 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
  * @tag: (allow-none): a #GtkTextTag, or %NULL
diff --git a/gtk/gtktextiter.h b/gtk/gtktextiter.h
index 994f9965d2..e1f7e07b1e 100644
--- a/gtk/gtktextiter.h
+++ b/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);