# HG changeset patch # User Francesco Potort # Date 1042585985 0 # Node ID 5856f0179746bd38ecb9ff7cd67d6edfd1e6c506 # Parent c1dbdec496c35486b2e0cc08884078d32ab5979a (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 -r c1dbdec496c3 -r 5856f0179746 src/textprop.c --- a/src/textprop.c Tue Jan 14 23:12:31 2003 +0000 +++ b/src/textprop.c Tue Jan 14 23:13:05 2003 +0000 @@ -177,7 +177,7 @@ if (NULL_INTERVAL_P (i)) return (force ? create_root_interval (object) : i); - + return find_interval (i, searchpos); } @@ -526,7 +526,7 @@ } #endif -/* Returns the interval of POSITION in OBJECT. +/* Returns the interval of POSITION in OBJECT. POSITION is BEG-based. */ INTERVAL @@ -563,15 +563,16 @@ 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 @@ 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 @@ 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 @@ 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 @@ if (! NILP (object)) CHECK_BUFFER (object); - + if (BUFFERP (object) && current_buffer != XBUFFER (object)) { record_unwind_protect (Fset_buffer, Fcurrent_buffer ()); @@ -794,7 +798,7 @@ } initial_value = Fget_char_property (position, prop, object); - + if (NILP (limit)) XSETFASTINT (limit, BUF_ZV (current_buffer)); else @@ -825,7 +829,10 @@ 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 @@ 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 @@ 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 @@ 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 @@ next = i; else next = next_interval (i); - + if (NULL_INTERVAL_P (next)) XSETFASTINT (position, (STRINGP (object) ? SCHARS (object) @@ -999,7 +1008,9 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ { 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 @@ for (; CONSP (list); list = XCDR (list)) { Lisp_Object item, end; - + item = XCAR (list); end = XCAR (XCDR (item)); @@ -2038,7 +2061,7 @@ 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 @@ 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 @@ 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 @@ interval_insert_behind_hooks = Qnil; interval_insert_in_front_hooks = Qnil; - + /* Common attributes one might give text */ staticpro (&Qforeground); @@ -2268,4 +2291,3 @@ /* defsubr (&Serase_text_properties); */ /* defsubr (&Scopy_text_properties); */ } -