GNU Info

Info Node: (elisp)Insertion

(elisp)Insertion


Next: Commands for Insertion Prev: Comparing Text Up: Text
Enter node , (file) or (file)node

Inserting Text
==============

   "Insertion" means adding new text to a buffer.  The inserted text
goes at point--between the character before point and the character
after point.  Some insertion functions leave point before the inserted
text, while other functions leave it after.  We call the former
insertion "after point" and the latter insertion "before point".

   Insertion relocates markers that point at positions after the
insertion point, so that they stay with the surrounding text (Note:
Markers).  When a marker points at the place of insertion, insertion
may or may not relocate the marker, depending on the marker's insertion
type (Note: Marker Insertion Types).  Certain special functions such
as `insert-before-markers' relocate all such markers to point after the
inserted text, regardless of the markers' insertion type.

   Insertion functions signal an error if the current buffer is
read-only or if they insert within read-only text.

   These functions copy text characters from strings and buffers along
with their properties.  The inserted characters have exactly the same
properties as the characters they were copied from.  By contrast,
characters specified as separate arguments, not part of a string or
buffer, inherit their text properties from the neighboring text.

   The insertion functions convert text from unibyte to multibyte in
order to insert in a multibyte buffer, and vice versa--if the text
comes from a string or from a buffer.  However, they do not convert
unibyte character codes 128 through 255 to multibyte characters, not
even if the current buffer is a multibyte buffer.  Note: Converting
Representations.

 - Function: insert &rest args
     This function inserts the strings and/or characters ARGS into the
     current buffer, at point, moving point forward.  In other words, it
     inserts the text before point.  An error is signaled unless all
     ARGS are either strings or characters.  The value is `nil'.

 - Function: insert-before-markers &rest args
     This function inserts the strings and/or characters ARGS into the
     current buffer, at point, moving point forward.  An error is
     signaled unless all ARGS are either strings or characters.  The
     value is `nil'.

     This function is unlike the other insertion functions in that it
     relocates markers initially pointing at the insertion point, to
     point after the inserted text.  If an overlay begins the insertion
     point, the inserted text falls outside the overlay; if a nonempty
     overlay ends at the insertion point, the inserted text falls
     inside that overlay.

 - Function: insert-char character &optional count inherit
     This function inserts COUNT instances of CHARACTER into the
     current buffer before point.  The argument COUNT should be a
     number (`nil' means 1), and CHARACTER must be a character.  The
     value is `nil'.

     This function does not convert unibyte character codes 128 through
     255 to multibyte characters, not even if the current buffer is a
     multibyte buffer.  Note: Converting Representations.

     If INHERIT is non-`nil', then the inserted characters inherit
     sticky text properties from the two characters before and after the
     insertion point.  Note: Sticky Properties.

 - Function: insert-buffer-substring from-buffer-or-name &optional
          start end
     This function inserts a portion of buffer FROM-BUFFER-OR-NAME
     (which must already exist) into the current buffer before point.
     The text inserted is the region from START and END.  (These
     arguments default to the beginning and end of the accessible
     portion of that buffer.)  This function returns `nil'.

     In this example, the form is executed with buffer `bar' as the
     current buffer.  We assume that buffer `bar' is initially empty.

          ---------- Buffer: foo ----------
          We hold these truths to be self-evident, that all
          ---------- Buffer: foo ----------
          
          (insert-buffer-substring "foo" 1 20)
               => nil
          
          ---------- Buffer: bar ----------
          We hold these truth-!-
          ---------- Buffer: bar ----------

   Note: Sticky Properties, for other insertion functions that inherit
text properties from the nearby text in addition to inserting it.
Whitespace inserted by indentation functions also inherits text
properties.


automatically generated by info2www version 1.2.2.9