---

9.6 Symbols with Position

A symbol with position is a symbol, the bare symbol, together with an unsigned integer called the position. These objects are intended for use by the byte compiler, which records in them the position of each symbol occurrence and uses those positions in warning and error messages.

The printed representation of a symbol with position uses the hash notation outlined in Printed Representation and Read Syntax. It looks like ‘#<symbol foo at 12345>’. It has no read syntax. You can cause just the bare symbol to be printed by binding the variable print-symbols-bare to non-nil around the print operation. The byte compiler does this before writing its output to the compiled Lisp file.

For most purposes, when the flag variable symbols-with-pos-enabled is non-nil, symbols with positions behave just as bare symbols do. For example, ‘(eq #<symbol foo at 12345> foo)’ has a value t when that variable is set (but nil when it isn’t set). Most of the time in Emacs this variable is nil, but the byte compiler binds it to t when it runs.

Typically, symbols with position are created by the byte compiler calling the reader function read-positioning-symbols (see Input Functions). One can also be created with the function position-symbol.

Variable: symbols-with-pos-enabled ¶

When this variable is non-nil, symbols with position behave like the contained bare symbol. Emacs runs a little more slowly in this case.

Variable: print-symbols-bare ¶

When bound to non-nil, the Lisp printer prints only the bare symbol of a symbol with position, ignoring the position.

Function: symbol-with-pos-p symbol. ¶

This function returns t if symbol is a symbol with position, nil otherwise.

Function: bare-symbol symbol ¶

This function returns the bare symbol contained in symbol, or symbol itself if it is already a bare symbol. For any other type of object, it signals an error.

Function: symbol-with-pos-pos symbol ¶

This function returns the position, a number, from a symbol with position. For any other type of object, it signals an error.

Function: position-symbol sym pos ¶

Make a new symbol with position. sym is either a bare symbol or a symbol with position, and supplies the symbol part of the new object. pos is either an integer which becomes the number part of the new object, or a symbol with position whose position is used. Emacs signals an error if either argument is invalid.