From: Francesco Potortì Date: Tue, 14 Jan 2003 23:13:05 +0000 (+0000) Subject: (Ftext_properties_at, Fnext_char_property_change) X-Git-Tag: ttn-vms-21-2-B4~11651 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=81f6e55f76cfc735cc28f3d85802311007808e89;p=emacs.git (Ftext_properties_at, Fnext_char_property_change) (Fprevious_char_property_change) (Fnext_single_char_property_change) (Fprevious_single_char_property_change, Fnext_property_change) (Fnext_single_property_change, Fprevious_property_change) (Fprevious_single_property_change, Fadd_text_properties) (Fput_text_property, Fset_text_properties) (Fremove_text_properties, Fremove_list_of_text_properties) (Ftext_property_any, Ftext_property_not_all): Clarify doc strings. --- diff --git a/src/textprop.c b/src/textprop.c index 745f6b7fb90..176607c5de4 100644 --- a/src/textprop.c +++ b/src/textprop.c @@ -177,7 +177,7 @@ validate_interval_range (object, begin, end, force) if (NULL_INTERVAL_P (i)) return (force ? create_root_interval (object) : i); - + return find_interval (i, searchpos); } @@ -526,7 +526,7 @@ erase_properties (i) } #endif -/* Returns the interval of POSITION in OBJECT. +/* Returns the interval of POSITION in OBJECT. POSITION is BEG-based. */ INTERVAL @@ -563,15 +563,16 @@ interval_of (position, object) args_out_of_range (make_number (position), make_number (position)); if (beg == end || NULL_INTERVAL_P (i)) return NULL_INTERVAL; - + return find_interval (i, position); } DEFUN ("text-properties-at", Ftext_properties_at, Stext_properties_at, 1, 2, 0, doc: /* Return the list of properties of the character at POSITION in OBJECT. -OBJECT is the string or buffer to look for the properties in; -nil means the current buffer. +If the optional second argument OBJECT is a buffer (or nil, which means +the current buffer), POSITION is a buffer position (integer or marker). +If OBJECT is a string, POSITION is a 0-based index into it. If POSITION is at the end of OBJECT, the value is nil. */) (position, object) Lisp_Object position, object; @@ -706,9 +707,9 @@ overlays are considered only if they are associated with OBJECT. */) DEFUN ("next-char-property-change", Fnext_char_property_change, Snext_char_property_change, 1, 2, 0, doc: /* Return the position of next text property or overlay change. -This scans characters forward from POSITION till it finds a change in -some text property, or the beginning or end of an overlay, and returns -the position of that. +This scans characters forward in the current buffer from POSITION till +it finds a change in some text property, or the beginning or end of an +overlay, and returns the position of that. If none is found, the function returns (point-max). If the optional third argument LIMIT is non-nil, don't search @@ -731,9 +732,9 @@ past position LIMIT; return LIMIT if nothing is found before LIMIT. */) DEFUN ("previous-char-property-change", Fprevious_char_property_change, Sprevious_char_property_change, 1, 2, 0, doc: /* Return the position of previous text property or overlay change. -Scans characters backward from POSITION till it finds a change in some -text property, or the beginning or end of an overlay, and returns the -position of that. +Scans characters backward in the current buffer from POSITION till it +finds a change in some text property, or the beginning or end of an +overlay, and returns the position of that. If none is found, the function returns (point-max). If the optional third argument LIMIT is non-nil, don't search @@ -759,7 +760,10 @@ DEFUN ("next-single-char-property-change", Fnext_single_char_property_change, doc: /* Return the position of next text property or overlay change for a specific property. Scans characters forward from POSITION till it finds a change in the PROP property, then returns the position of the change. -The optional third argument OBJECT is the string or buffer to scan. +If the optional third argument OBJECT is a buffer (or nil, which means +the current buffer), POSITION is a buffer position (integer or marker). +If OBJECT is a string, POSITION is a 0-based index into it. + The property values are compared with `eq'. If the property is constant all the way to the end of OBJECT, return the last valid position in OBJECT. @@ -786,7 +790,7 @@ past position LIMIT; return LIMIT if nothing is found before LIMIT. */) if (! NILP (object)) CHECK_BUFFER (object); - + if (BUFFERP (object) && current_buffer != XBUFFER (object)) { record_unwind_protect (Fset_buffer, Fcurrent_buffer ()); @@ -794,7 +798,7 @@ past position LIMIT; return LIMIT if nothing is found before LIMIT. */) } initial_value = Fget_char_property (position, prop, object); - + if (NILP (limit)) XSETFASTINT (limit, BUF_ZV (current_buffer)); else @@ -825,7 +829,10 @@ DEFUN ("previous-single-char-property-change", doc: /* Return the position of previous text property or overlay change for a specific property. Scans characters backward from POSITION till it finds a change in the PROP property, then returns the position of the change. -The optional third argument OBJECT is the string or buffer to scan. +If the optional third argument OBJECT is a buffer (or nil, which means +the current buffer), POSITION is a buffer position (integer or marker). +If OBJECT is a string, POSITION is a 0-based index into it. + The property values are compared with `eq'. If the property is constant all the way to the start of OBJECT, return the first valid position in OBJECT. @@ -851,13 +858,13 @@ back past position LIMIT; return LIMIT if nothing is found before LIMIT. */) if (! NILP (object)) CHECK_BUFFER (object); - + if (BUFFERP (object) && current_buffer != XBUFFER (object)) { record_unwind_protect (Fset_buffer, Fcurrent_buffer ()); Fset_buffer (object); } - + if (NILP (limit)) XSETFASTINT (limit, BUF_BEGV (current_buffer)); else @@ -870,7 +877,7 @@ back past position LIMIT; return LIMIT if nothing is found before LIMIT. */) Lisp_Object initial_value = Fget_char_property (make_number (XFASTINT (position) - 1), prop, object); - + for (;;) { position = Fprevious_char_property_change (position, limit); @@ -903,7 +910,9 @@ DEFUN ("next-property-change", Fnext_property_change, doc: /* Return the position of next property change. Scans characters forward from POSITION in OBJECT till it finds a change in some text property, then returns the position of the change. -The optional second argument OBJECT is the string or buffer to scan. +If the optional second argument OBJECT is a buffer (or nil, which means +the current buffer), POSITION is a buffer position (integer or marker). +If OBJECT is a string, POSITION is a 0-based index into it. Return nil if the property is constant all the way to the end of OBJECT. If the value is non-nil, it is a position greater than POSITION, never equal. @@ -930,7 +939,7 @@ past position LIMIT; return LIMIT if nothing is found before LIMIT. */) next = i; else next = next_interval (i); - + if (NULL_INTERVAL_P (next)) XSETFASTINT (position, (STRINGP (object) ? SCHARS (object) @@ -999,7 +1008,9 @@ DEFUN ("next-single-property-change", Fnext_single_property_change, doc: /* Return the position of next property change for a specific property. Scans characters forward from POSITION till it finds a change in the PROP property, then returns the position of the change. -The optional third argument OBJECT is the string or buffer to scan. +If the optional third argument OBJECT is a buffer (or nil, which means +the current buffer), POSITION is a buffer position (integer or marker). +If OBJECT is a string, POSITION is a 0-based index into it. The property values are compared with `eq'. Return nil if the property is constant all the way to the end of OBJECT. If the value is non-nil, it is a position greater than POSITION, never equal. @@ -1024,7 +1035,7 @@ past position LIMIT; return LIMIT if nothing is found before LIMIT. */) here_val = textget (i->plist, prop); next = next_interval (i); - while (! NULL_INTERVAL_P (next) + while (! NULL_INTERVAL_P (next) && EQ (here_val, textget (next->plist, prop)) && (NILP (limit) || next->position < XFASTINT (limit))) next = next_interval (next); @@ -1046,7 +1057,9 @@ DEFUN ("previous-property-change", Fprevious_property_change, doc: /* Return the position of previous property change. Scans characters backwards from POSITION in OBJECT till it finds a change in some text property, then returns the position of the change. -The optional second argument OBJECT is the string or buffer to scan. +If the optional second argument OBJECT is a buffer (or nil, which means +the current buffer), POSITION is a buffer position (integer or marker). +If OBJECT is a string, POSITION is a 0-based index into it. Return nil if the property is constant all the way to the start of OBJECT. If the value is non-nil, it is a position less than POSITION, never equal. @@ -1091,7 +1104,9 @@ DEFUN ("previous-single-property-change", Fprevious_single_property_change, doc: /* Return the position of previous property change for a specific property. Scans characters backward from POSITION till it finds a change in the PROP property, then returns the position of the change. -The optional third argument OBJECT is the string or buffer to scan. +If the optional third argument OBJECT is a buffer (or nil, which means +the current buffer), POSITION is a buffer position (integer or marker). +If OBJECT is a string, POSITION is a 0-based index into it. The property values are compared with `eq'. Return nil if the property is constant all the way to the start of OBJECT. If the value is non-nil, it is a position less than POSITION, never equal. @@ -1142,9 +1157,10 @@ DEFUN ("add-text-properties", Fadd_text_properties, Sadd_text_properties, 3, 4, 0, doc: /* Add properties to the text from START to END. The third argument PROPERTIES is a property list -specifying the property values to add. -The optional fourth argument, OBJECT, -is the string or buffer containing the text. +specifying the property values to add. If the optional fourth argument +OBJECT is a buffer (or nil, which means the current buffer), +START and END are buffer positions (integers or markers). +If OBJECT is a string, START and END are 0-based indices into it. Return t if any property value actually changed, nil otherwise. */) (start, end, properties, object) Lisp_Object start, end, properties, object; @@ -1251,8 +1267,9 @@ DEFUN ("put-text-property", Fput_text_property, doc: /* Set one property of the text from START to END. The third and fourth arguments PROPERTY and VALUE specify the property to add. -The optional fifth argument, OBJECT, -is the string or buffer containing the text. */) +If the optional fifth argument OBJECT is a buffer (or nil, which means +the current buffer), START and END are buffer positions (integers or +markers). If OBJECT is a string, START and END are 0-based indices into it. */) (start, end, property, value, object) Lisp_Object start, end, property, value, object; { @@ -1266,9 +1283,9 @@ DEFUN ("set-text-properties", Fset_text_properties, Sset_text_properties, 3, 4, 0, doc: /* Completely replace properties of text from START to END. The third argument PROPERTIES is the new property list. -The optional fourth argument, OBJECT, -is the string or buffer containing the text. -If OBJECT is omitted or nil, it defaults to the current buffer. +If the optional fourth argument OBJECT is a buffer (or nil, which means +the current buffer), START and END are buffer positions (integers or +markers). If OBJECT is a string, START and END are 0-based indices into it. If PROPERTIES is nil, the effect is to remove all properties from the designated part of OBJECT. */) (start, end, properties, object) @@ -1436,9 +1453,12 @@ DEFUN ("remove-text-properties", Fremove_text_properties, The third argument PROPERTIES is a property list whose property names specify the properties to remove. \(The values stored in PROPERTIES are ignored.) -The optional fourth argument, OBJECT, -is the string or buffer containing the text. -Return t if any property was actually removed, nil otherwise. */) +If the optional fourth argument OBJECT is a buffer (or nil, which means +the current buffer), START and END are buffer positions (integers or +markers). If OBJECT is a string, START and END are 0-based indices into it. +Return t if any property was actually removed, nil otherwise. + +Use set-text-properties if you want to remove all text properties. */) (start, end, properties, object) Lisp_Object start, end, properties, object; { @@ -1521,8 +1541,9 @@ DEFUN ("remove-list-of-text-properties", Fremove_list_of_text_properties, Sremove_list_of_text_properties, 3, 4, 0, doc: /* Remove some properties from text from START to END. The third argument LIST-OF-PROPERTIES is a list of property names to remove. -The optional fourth argument, OBJECT, -is the string or buffer containing the text, defaulting to the current buffer. +If the optional fourth argument OBJECT is a buffer (or nil, which means +the current buffer), START and END are buffer positions (integers or +markers). If OBJECT is a string, START and END are 0-based indices into it. Return t if any property was actually removed, nil otherwise. */) (start, end, list_of_properties, object) Lisp_Object start, end, list_of_properties, object; @@ -1609,8 +1630,9 @@ DEFUN ("text-property-any", Ftext_property_any, doc: /* Check text from START to END for property PROPERTY equalling VALUE. If so, return the position of the first character whose property PROPERTY is `eq' to VALUE. Otherwise return nil. -The optional fifth argument, OBJECT, is the string or buffer -containing the text. */) +If the optional fifth argument OBJECT is a buffer (or nil, which means +the current buffer), START and END are buffer positions (integers or +markers). If OBJECT is a string, START and END are 0-based indices into it. */) (start, end, property, value, object) Lisp_Object start, end, property, value, object; { @@ -1645,8 +1667,9 @@ DEFUN ("text-property-not-all", Ftext_property_not_all, doc: /* Check text from START to END for property PROPERTY not equalling VALUE. If so, return the position of the first character whose property PROPERTY is not `eq' to VALUE. Otherwise, return nil. -The optional fifth argument, OBJECT, is the string or buffer -containing the text. */) +If the optional fifth argument OBJECT is a buffer (or nil, which means +the current buffer), START and END are buffer positions (integers or +markers). If OBJECT is a string, START and END are 0-based indices into it. */) (start, end, property, value, object) Lisp_Object start, end, property, value, object; { @@ -1850,23 +1873,23 @@ text_property_list (object, start, end, prop) Lisp_Object result; result = Qnil; - + i = validate_interval_range (object, &start, &end, soft); if (!NULL_INTERVAL_P (i)) { int s = XINT (start); int e = XINT (end); - + while (s < e) { int interval_end, len; Lisp_Object plist; - + interval_end = i->position + LENGTH (i); if (interval_end > e) interval_end = e; len = interval_end - s; - + plist = i->plist; if (!NILP (prop)) @@ -1882,14 +1905,14 @@ text_property_list (object, start, end, prop) Fcons (make_number (s + len), Fcons (plist, Qnil))), result); - + i = next_interval (i); if (NULL_INTERVAL_P (i)) break; s = i->position; } } - + return result; } @@ -1906,18 +1929,18 @@ add_text_properties_from_list (object, list, delta) { struct gcpro gcpro1, gcpro2; int modified_p = 0; - + GCPRO2 (list, object); - + for (; CONSP (list); list = XCDR (list)) { Lisp_Object item, start, end, plist, tem; - + item = XCAR (list); start = make_number (XINT (XCAR (item)) + XINT (delta)); end = make_number (XINT (XCAR (XCDR (item))) + XINT (delta)); plist = XCAR (XCDR (XCDR (item))); - + tem = Fadd_text_properties (start, end, plist, object); if (!NILP (tem)) modified_p = 1; @@ -1940,7 +1963,7 @@ extend_property_ranges (list, old_end, new_end) for (; CONSP (list); list = XCDR (list)) { Lisp_Object item, end; - + item = XCAR (list); end = XCAR (XCDR (item)); @@ -2038,7 +2061,7 @@ verify_interval_modification (buf, start, end) if (! NULL_INTERVAL_P (i)) { after = textget (i->plist, Qread_only); - + /* If interval I is read-only and read-only is front-sticky, inhibit insertion. Check for read-only as well as category. */ @@ -2058,7 +2081,7 @@ verify_interval_modification (buf, start, end) if (! NULL_INTERVAL_P (prev)) { before = textget (prev->plist, Qread_only); - + /* If interval PREV is read-only and read-only isn't rear-nonsticky, inhibit insertion. Check for read-only as well as category. */ @@ -2078,7 +2101,7 @@ verify_interval_modification (buf, start, end) else if (! NULL_INTERVAL_P (i)) { after = textget (i->plist, Qread_only); - + /* If interval I is read-only and read-only is front-sticky, inhibit insertion. Check for read-only as well as category. */ @@ -2206,7 +2229,7 @@ rear-nonsticky properties of the character overrides NONSTICKINESS. */); interval_insert_behind_hooks = Qnil; interval_insert_in_front_hooks = Qnil; - + /* Common attributes one might give text */ staticpro (&Qforeground); @@ -2268,4 +2291,3 @@ rear-nonsticky properties of the character overrides NONSTICKINESS. */); /* defsubr (&Serase_text_properties); */ /* defsubr (&Scopy_text_properties); */ } -