+File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
+
+Active Display Table
+--------------------
+
+ The active display table is controlled by the variable
+`current-display-table'. This is a specifier, which means that you can
+specify separate values for it in individual buffers, windows, frames,
+and devices, as well as a global value. It also means that you cannot
+set this variable using `setq'; use `set-specifier' instead. *Note
+Specifiers::. (FSF Emacs uses `window-display-table',
+`buffer-display-table', `standard-display-table', etc. to control the
+display table. However, specifiers are a cleaner and more powerful way
+of doing the same thing. FSF Emacs also uses a different format for
+the contents of a display table, using additional indirection to a
+"glyph table" and such. Note that "glyph" has a different meaning in
+XEmacs.)
+
+ - Variable: current-display-table
+ The display table currently in use. This is a specifier.
+
+ Display tables are used to control how characters are displayed.
+ Each time that redisplay processes a character, it is looked up in
+ all the display tables that apply (obtained by calling
+ `specifier-instance' on `current-display-table' and any overriding
+ display tables specified in currently active faces). The first
+ entry found that matches the character determines how the
+ character is displayed. If there is no matching entry, the
+ default display method is used. (Non-control characters are
+ displayed as themselves and control characters are displayed
+ according to the buffer-local variable `ctl-arrow'. Control
+ characters are further affected by `control-arrow-glyph' and
+ `octal-escape-glyph'.)
+
+ Each instantiator in this specifier and the display-table
+ specifiers in faces is a display table or a list of such tables.
+ If a list, each table will be searched in turn for an entry
+ matching a particular character. Each display table is one of
+
+ * A vector, specifying values for characters starting at 0.
+
+ * A char table, either of type `char' or `generic'.
+
+ * A range table.
+
+ Each entry in a display table should be one of
+
+ * nil (this entry is ignored and the search continues).
+
+ * A character (use this character; if it happens to be the same
+ as the original character, default processing happens,
+ otherwise redisplay attempts to display this character
+ directly; #### At some point recursive display-table lookup
+ will be implemented).
+
+ * A string (display each character in the string directly; ####
+ At some point recursive display-table lookup will be
+ implemented).
+
+ * A glyph (display the glyph; #### At some point recursive
+ display-table lookup will be implemented when a string glyph
+ is being processed).
+
+ * A cons of the form (format "STRING") where STRING is a
+ printf-like spec used to process the character. ####
+ Unfortunately no formatting directives other than %% are
+ implemented.
+
+ * A vector (each element of the vector is processed recursively;
+ in such a case, nil elements in the vector are simply
+ ignored).
+
+ #### At some point in the near future, display tables are
+ likely to be expanded to include other features, such as
+ referencing characters in particular fonts and allowing the
+ character search to continue all the way up the chain of
+ specifier instantiators. These features are necessary to
+ properly display Unicode characters.
+
+ Individual faces can also specify an overriding display table; this
+is set using `set-face-display-table'. *Note Faces::.
+
+ If no display table can be determined for a particular window, then
+XEmacs uses the usual display conventions. *Note Usual Display::.
+
+\1f
+File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
+
+Character Descriptors
+---------------------
+
+ Each element of the display-table vector describes how to display a
+particular character and is called a "character descriptor". A
+character descriptor can be:
+
+a string
+ Display this particular string wherever the character is to be
+ displayed.
+
+a glyph
+ Display this particular glyph wherever the character is to be
+ displayed.
+
+a vector
+ The vector may contain strings and/or glyphs. Display the
+ elements of the vector one after another wherever the character is
+ to be displayed.
+
+`nil'
+ Display according to the standard interpretation (*note Usual
+ Display::).
+
+\1f
+File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
+
+Beeping
+=======
+
+ You can make XEmacs ring a bell, play a sound, or blink the screen to
+attract the user's attention. Be conservative about how often you do
+this; frequent bells can become irritating. Also be careful not to use
+beeping alone when signaling an error is appropriate. (*Note Errors::.)
+
+ - Function: ding &optional dont-terminate sound device
+ This function beeps, or flashes the screen (see `visible-bell'
+ below). It also terminates any keyboard macro currently executing
+ unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
+ should be a symbol specifying which sound to make. This sound
+ will be played if `visible-bell' is `nil'. (This only works if
+ sound support was compiled into the executable and you are running
+ on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
+ PC. Otherwise you just get a beep.) The optional third argument
+ specifies what device to make the sound on, and defaults to the
+ selected device.
+
+ - Function: beep &optional dont-terminate sound device
+ This is a synonym for `ding'.
+
+ - User Option: visible-bell
+ This variable determines whether XEmacs should flash the screen to
+ represent a bell. Non-`nil' means yes, `nil' means no. On TTY
+ devices, this is effective only if the Termcap entry for the
+ terminal type has the visible bell flag (`vb') set.
+
+ - Variable: sound-alist
+ This variable holds an alist associating names with sounds. When
+ `beep' or `ding' is called with one of the name symbols, the
+ associated sound will be generated instead of the standard beep.
+
+ Each element of `sound-alist' is a list describing a sound. The
+ first element of the list is the name of the sound being defined.
+ Subsequent elements of the list are alternating keyword/value
+ pairs:
+
+ `sound'
+ A string of raw sound data, or the name of another sound to
+ play. The symbol `t' here means use the default X beep.
+
+ `volume'
+ An integer from 0-100, defaulting to `bell-volume'.
+
+ `pitch'
+ If using the default X beep, the pitch (Hz) to generate.
+
+ `duration'
+ If using the default X beep, the duration (milliseconds).
+
+ For compatibility, elements of `sound-alist' may also be:
+
+ * `( sound-name . <sound> )'
+
+ * `( sound-name <volume> <sound> )'
+
+ You should probably add things to this list by calling the function
+ `load-sound-file'.
+
+ Caveats:
+
+ - You can only play audio data if running on the console screen
+ of a Sun SparcStation, SGI, or HP9000s700.
+
+ - The pitch, duration, and volume options are available
+ everywhere, but many X servers ignore the `pitch' option.
+
+ The following beep-types are used by XEmacs itself:
+
+ `auto-save-error'
+ when an auto-save does not succeed
+
+ `command-error'
+ when the XEmacs command loop catches an error
+
+ `undefined-key'
+ when you type a key that is undefined
+
+ `undefined-click'
+ when you use an undefined mouse-click combination
+
+ `no-completion'
+ during completing-read
+
+ `y-or-n-p'
+ when you type something other than 'y' or 'n'
+
+ `yes-or-no-p'
+ when you type something other than 'yes' or 'no'
+
+ `default'
+ used when nothing else is appropriate.
+
+ Other lisp packages may use other beep types, but these are the
+ ones that the C kernel of XEmacs uses.
+
+ - User Option: bell-volume
+ This variable specifies the default volume for sounds, from 0 to
+ 100.
+
+ - Command: load-default-sounds
+ This function loads and installs some sound files as beep-types.
+
+ - Command: load-sound-file filename sound-name &optional volume
+ This function reads in an audio file and adds it to `sound-alist'.
+ The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
+ should be a symbol, specifying the name of the sound. If VOLUME
+ is specified, the sound will be played at that volume; otherwise,
+ the value of BELL-VOLUME will be used.
+
+ - Function: play-sound sound &optional volume device
+ This function plays sound SOUND, which should be a symbol
+ mentioned in `sound-alist'. If VOLUME is specified, it overrides
+ the value (if any) specified in `sound-alist'. DEVICE specifies
+ the device to play the sound on, and defaults to the selected
+ device.
+
+ - Command: play-sound-file file &optional volume device
+ This function plays the named sound file at volume VOLUME, which
+ defaults to `bell-volume'. DEVICE specifies the device to play
+ the sound on, and defaults to the selected device.
+
+\1f
+File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
+
+Hash Tables
+***********
+
+ - Function: hash-table-p object
+ This function returns `t' if OBJECT is a hash table, else `nil'.
+
+* Menu:
+
+* Introduction to Hash Tables:: Hash tables are fast data structures for
+ implementing simple tables (i.e. finite
+ mappings from keys to values).
+* Working With Hash Tables:: Hash table functions.
+* Weak Hash Tables:: Hash tables with special garbage-collection
+ behavior.
+
+\1f
+File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
+
+Introduction to Hash Tables
+===========================
+
+ A "hash table" is a data structure that provides mappings from
+arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
+called "values". A key/value pair is sometimes called an "entry" in
+the hash table. There are many ways other than hash tables of
+implementing the same sort of mapping, e.g. association lists (*note
+Association Lists::) and property lists (*note Property Lists::), but
+hash tables provide much faster lookup when there are many entries in
+the mapping. Hash tables are an implementation of the abstract data
+type "dictionary", also known as "associative array".
+
+ Internally, hash tables are hashed using the "linear probing" hash
+table implementation method. This method hashes each key to a
+particular spot in the hash table, and then scans forward sequentially
+until a blank entry is found. To look up a key, hash to the appropriate
+spot, then search forward for the key until either a key is found or a
+blank entry stops the search. This method is used in preference to
+double hashing because of changes in recent hardware. The penalty for
+non-sequential access to memory has been increasing, and this
+compensates for the problem of clustering that linear probing entails.
+
+ When hash tables are created, the user may (but is not required to)
+specify initial properties that influence performance.
+
+ Use the `:size' parameter to specify the number of entries that are
+likely to be stored in the hash table, to avoid the overhead of resizing
+the table. But if the pre-allocated space for the entries is never
+used, it is simply wasted and makes XEmacs slower. Excess unused hash
+table entries exact a small continuous performance penalty, since they
+must be scanned at every garbage collection. If the number of entries
+in the hash table is unknown, simply avoid using the `:size' keyword.
+
+ Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
+the algorithm for deciding when to rehash the hash table. For
+temporary hash tables that are going to be very heavily used, use a
+small rehash threshold, for example, 0.4 and a large rehash size, for
+example 2.0. For permanent hash tables that will be infrequently used,
+specify a large rehash threshold, for example 0.8.
+
+ Hash tables can also be created by the lisp reader using structure
+syntax, for example:
+ #s(hash-table size 20 data (foo 1 bar 2))
+
+ The structure syntax accepts the same keywords as `make-hash-table'
+(without the `:' character), as well as the additional keyword `data',
+which specifies the initial hash table contents.
+
+ - Function: make-hash-table &key `test' `size' `rehash-size'
+ `rehash-threshold' `weakness'
+ This function returns a new empty hash table object.
+
+ Keyword `:test' can be `eq', `eql' (default) or `equal'.
+ Comparison between keys is done using this function. If speed is
+ important, consider using `eq'. When storing strings in the hash
+ table, you will likely need to use `equal'.
+
+ Keyword `:size' specifies the number of keys likely to be inserted.
+ This number of entries can be inserted without enlarging the hash
+ table.
+
+ Keyword `:rehash-size' must be a float greater than 1.0, and
+ specifies the factor by which to increase the size of the hash
+ table when enlarging.
+
+ Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
+ and specifies the load factor of the hash table which triggers
+ enlarging.
+
+ Non-standard keyword `:weakness' can be `nil' (default), `t',
+ `key-and-value', `key', `value' or `key-or-value'. `t' is an
+ alias for `key-and-value'.
+
+ A key-and-value-weak hash table, also known as a fully-weak or
+ simply as a weak hash table, is one whose pointers do not count as
+ GC referents: for any key-value pair in the hash table, if the only
+ remaining pointer to either the key or the value is in a weak hash
+ table, then the pair will be removed from the hash table, and the
+ key and value collected. A non-weak hash table (or any other
+ pointer) would prevent the object from being collected.
+
+ A key-weak hash table is similar to a fully-weak hash table except
+ that a key-value pair will be removed only if the key remains
+ unmarked outside of weak hash tables. The pair will remain in the
+ hash table if the key is pointed to by something other than a weak
+ hash table, even if the value is not.
+
+ A value-weak hash table is similar to a fully-weak hash table
+ except that a key-value pair will be removed only if the value
+ remains unmarked outside of weak hash tables. The pair will
+ remain in the hash table if the value is pointed to by something
+ other than a weak hash table, even if the key is not.
+
+ A key-or-value-weak hash table is similar to a fully-weak hash
+ table except that a key-value pair will be removed only if the
+ value and the key remain unmarked outside of weak hash tables.
+ The pair will remain in the hash table if the value or key are
+ pointed to by something other than a weak hash table, even if the
+ other is not.
+
+ - Function: copy-hash-table hash-table
+ This function returns a new hash table which contains the same
+ keys and values as HASH-TABLE. The keys and values will not
+ themselves be copied.
+
+ - Function: hash-table-count hash-table
+ This function returns the number of entries in HASH-TABLE.
+
+ - Function: hash-table-test hash-table
+ This function returns the test function of HASH-TABLE. This can
+ be one of `eq', `eql' or `equal'.
+
+ - Function: hash-table-size hash-table
+ This function returns the current number of slots in HASH-TABLE,
+ whether occupied or not.
+
+ - Function: hash-table-rehash-size hash-table
+ This function returns the current rehash size of HASH-TABLE. This
+ is a float greater than 1.0; the factor by which HASH-TABLE is
+ enlarged when the rehash threshold is exceeded.
+
+ - Function: hash-table-rehash-threshold hash-table
+ This function returns the current rehash threshold of HASH-TABLE.
+ This is a float between 0.0 and 1.0; the maximum "load factor" of
+ HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
+
+ - Function: hash-table-weakness hash-table
+ This function returns the weakness of HASH-TABLE. This can be one
+ of `nil', `t', `key' or `value'.
+
+\1f
+File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
+
+Working With Hash Tables
+========================
+
+ - Function: puthash key value hash-table
+ This function hashes KEY to VALUE in HASH-TABLE.
+
+ - Function: gethash key hash-table &optional default
+ This function finds the hash value for KEY in HASH-TABLE. If
+ there is no entry for KEY in HASH-TABLE, DEFAULT is returned
+ (which in turn defaults to `nil').
+
+ - Function: remhash key hash-table
+ This function removes the entry for KEY from HASH-TABLE. Does
+ nothing if there is no entry for KEY in HASH-TABLE.
+
+ - Function: clrhash hash-table
+ This function removes all entries from HASH-TABLE, leaving it
+ empty.
+
+ - Function: maphash function hash-table
+ This function maps FUNCTION over entries in HASH-TABLE, calling it
+ with two args, each key and value in the hash table.
+
+ FUNCTION may not modify HASH-TABLE, with the one exception that
+ FUNCTION may remhash or puthash the entry currently being
+ processed by FUNCTION.
+
+\1f