Function: make-hash-table

make-hash-table is a function defined in fns.c.

Signature

(make-hash-table &rest KEYWORD-ARGS)

Documentation

Create and return a new hash table.

Arguments are specified as keyword/argument pairs. The following arguments are defined:

:test TEST -- TEST must be a symbol that specifies how to compare
keys. Default is eql. Predefined are the tests eq, eql, and equal. User-supplied test and hash functions can be specified via define-hash-table-test.

:size SIZE -- A hint as to how many elements will be put in the table.
The table will always grow as needed; this argument may help performance slightly if the size is known in advance but is never required.

:weakness WEAK -- WEAK must be one of nil, t, key, value,
key-or-value, or key-and-value. If WEAK is not nil, the table returned is a weak table. Key/value pairs are removed from a weak hash table when there are no non-weak references pointing to their key, value, one of key or value, or both key and value, depending on WEAK. WEAK t is equivalent to key-and-value. Default value of WEAK is nil.

:purecopy PURECOPY -- If PURECOPY is non-nil, the table can be copied
to pure storage when Emacs is being dumped, making the contents of the table read only. Any further changes to purified tables will result in an error.

The keywords arguments :rehash-threshold and :rehash-size are obsolete and ignored.

Other relevant functions are documented in the hash-table group.

View in manual

Probably introduced at or before Emacs version 21.1.

Shortdoc

;; hash-table
(make-hash-table)
    => #s(hash-table ...)

Aliases

cl-make-hash-table (obsolete since 24.3)

Source Code

// Defined in /usr/src/emacs/src/fns.c
{
  USE_SAFE_ALLOCA;

  /* The vector `used' is used to keep track of arguments that
     have been consumed.  */
  char *used = SAFE_ALLOCA (nargs * sizeof *used);
  memset (used, 0, nargs * sizeof *used);

  /* See if there's a `:test TEST' among the arguments.  */
  ptrdiff_t i = get_key_arg (QCtest, nargs, args, used);
  Lisp_Object test = i ? maybe_remove_pos_from_symbol (args[i]) : Qeql;
  const struct hash_table_test *testdesc;
  if (BASE_EQ (test, Qeq))
    testdesc = &hashtest_eq;
  else if (BASE_EQ (test, Qeql))
    testdesc = &hashtest_eql;
  else if (BASE_EQ (test, Qequal))
    testdesc = &hashtest_equal;
  else
    testdesc = get_hash_table_user_test (test);

  /* See if there's a `:purecopy PURECOPY' argument.  */
  i = get_key_arg (QCpurecopy, nargs, args, used);
  bool purecopy = i && !NILP (args[i]);
  /* See if there's a `:size SIZE' argument.  */
  i = get_key_arg (QCsize, nargs, args, used);
  Lisp_Object size_arg = i ? args[i] : Qnil;
  EMACS_INT size;
  if (NILP (size_arg))
    size = DEFAULT_HASH_SIZE;
  else if (FIXNATP (size_arg))
    size = XFIXNAT (size_arg);
  else
    signal_error ("Invalid hash table size", size_arg);

  /* Look for `:weakness WEAK'.  */
  i = get_key_arg (QCweakness, nargs, args, used);
  Lisp_Object weakness = i ? args[i] : Qnil;
  hash_table_weakness_t weak;
  if (NILP (weakness))
    weak = Weak_None;
  else if (EQ (weakness, Qkey))
    weak = Weak_Key;
  else if (EQ (weakness, Qvalue))
    weak = Weak_Value;
  else if (EQ (weakness, Qkey_or_value))
    weak = Weak_Key_Or_Value;
  else if (EQ (weakness, Qt) || EQ (weakness, Qkey_and_value))
    weak = Weak_Key_And_Value;
  else
    signal_error ("Invalid hash table weakness", weakness);

  /* Now, all args should have been used up, or there's a problem.  */
  for (i = 0; i < nargs; ++i)
    if (!used[i])
      {
	/* Ignore obsolete arguments.  */
	if (EQ (args[i], QCrehash_threshold) || EQ (args[i], QCrehash_size))
	  i++;
	else
	  signal_error ("Invalid argument list", args[i]);
      }

  SAFE_FREE ();
  return make_hash_table (testdesc, size, weak, purecopy);
}