9.6 Symbols with Position

A symbol with position is a symbol, called the bare symbol, together with a nonnegative fixnum called the position. Even though a symbol with position often acts like its bare symbol, it is not a symbol: instead, it is an object that has both a bare symbol and a position. Because symbols with position are not symbols, they don’t have entries in the obarray, though their bare symbols typically do (see Creating and Interning Symbols).

The byte compiler uses symbols with position, records in them the position of each symbol occurrence, and uses those positions in warning and error messages. They shouldn’t normally be used otherwise. Doing so can cause unexpected results with basic Emacs functions such as eq and equal.

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.

When the flag variable symbols-with-pos-enabled is non-nil, a symbol with position ordinarily behaves like its bare symbol. For example, ‘(eq (position-symbol 'foo 12345) 'foo)’ yields t, and equal likewise treats a symbol with position as its bare symbol.

When symbols-with-pos-enabled is nil, symbols with position behave as themselves, not as symbols. For example, ‘(eq (position-symbol 'foo 12345) 'foo)’ yields nil, and equal likewise treats a symbol with position as not equal to its bare symbol.

Most of the time in Emacs symbols-with-pos-enabled is nil, but the byte compiler and the native compiler bind it to t when they run and Emacs runs a little more slowly in this case.

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 ¶

This variable affects the behavior of symbols with position when they are not being printed and are not arguments to one of the functions defined later in this section. When this variable is non-nil, such a symbol with position behaves like its bare symbol; otherwise it behaves as itself, not as a symbol.

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. Otherwise a symbol with position prints as itself, not as a symbol.

Function: symbol-with-pos-p object ¶

This function returns t if object is a symbol with position, nil otherwise. Unlike symbolp, this function ignores symbols-with-pos-enabled.

Function: bare-symbol sym ¶

This function returns the bare symbol of the symbol with position sym, or sym itself if it is already a symbol. For any other type of object, it signals an error. This function ignores symbols-with-pos-enabled.

Function: symbol-with-pos-pos sympos ¶

This function returns the position, a nonnegative fixnum, from the symbol with position sympos. For any other type of object, it signals an error. This function ignores symbols-with-pos-enabled.

Function: position-symbol sym pos ¶

Make a new symbol with position. The new object’s bare symbol is taken from sym, which is either a symbol, or a symbol with position whose bare symbol is used. The new object’s position is taken from pos, which is either a nonnegative fixnum, or a symbol with position whose position is used. Emacs signals an error if either argument is invalid. This function ignores symbols-with-pos-enabled.