-\1f
-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.
-
- Keyword `:weakness' can be `nil' (default), `t', `key' or `value'.
-
- 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.
-
- - 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.
-