Function: try-completion
try-completion is a function defined in minibuf.c.
Signature
(try-completion STRING COLLECTION &optional PREDICATE)
Documentation
Return longest common substring of all completions of STRING in COLLECTION.
Test each possible completion specified by COLLECTION
to see if it begins with STRING. The possible completions may be
strings or symbols. Symbols are converted to strings before testing,
by using symbol-name.
If no possible completions match, the function returns nil; if there's just one exact match, it returns t; otherwise it returns the longest initial substring common to all possible completions that begin with STRING.
If COLLECTION is an alist, the keys (cars of elements) are the possible completions. If an element is not a cons cell, then the element itself is a possible completion. If COLLECTION is a hash-table, all the keys that are either strings or symbols are the possible completions. If COLLECTION is an obarray, the names of all symbols in the obarray are the possible completions.
COLLECTION can also be a function to do the completion itself.
It receives three arguments: STRING, PREDICATE and nil.
Whatever it returns becomes the value of try-completion.
If optional third argument PREDICATE is non-nil, it must be a function of one or two arguments, and is used to test each possible completion. A possible completion is accepted only if PREDICATE returns non-nil.
The argument given to PREDICATE is either a string or a cons cell (whose car is a string) from the alist, or a symbol from the obarray. If COLLECTION is a hash-table, PREDICATE is called with two arguments: the string key and the associated value.
To be acceptable, a possible completion must also match all the regexps
in completion-regexp-list (unless COLLECTION is a function, in
which case that function should itself handle completion-regexp-list).
If completion-ignore-case is non-nil, possible completions are matched
while ignoring letter-case, but no guarantee is made about the letter-case
of the return value, except that it comes either from the user's input
or from one of the possible completions.
Other relevant functions are documented in the string group.
Probably introduced at or before Emacs version 19.23.
Shortdoc
;; string
(try-completion "foo" '("foobar" "foozot" "gazonk"))
=> "foo"Source Code
// Defined in /usr/src/emacs/src/minibuf.c
// Skipping highlighting due to helpful-max-highlight.
{
Lisp_Object bestmatch, tail, elt, eltstring;
/* Size in bytes of BESTMATCH. */
ptrdiff_t bestmatchsize = 0;
/* These are in bytes, too. */
ptrdiff_t compare, matchsize;
enum { function_table, list_table, obarray_table, hash_table}
type = (HASH_TABLE_P (collection) ? hash_table
: VECTORP (collection) ? obarray_table
: ((NILP (collection)
|| (CONSP (collection) && !FUNCTIONP (collection)))
? list_table : function_table));
ptrdiff_t idx = 0, obsize = 0;
int matchcount = 0;
Lisp_Object bucket, zero, end, tem;
CHECK_STRING (string);
if (type == function_table)
return call3 (collection, string, predicate, Qnil);
bestmatch = bucket = Qnil;
zero = make_fixnum (0);
/* If COLLECTION is not a list, set TAIL just for gc pro. */
tail = collection;
if (type == obarray_table)
{
collection = check_obarray (collection);
obsize = ASIZE (collection);
bucket = AREF (collection, idx);
}
while (1)
{
/* Get the next element of the alist, obarray, or hash-table. */
/* Exit the loop if the elements are all used up. */
/* elt gets the alist element or symbol.
eltstring gets the name to check as a completion. */
if (type == list_table)
{
if (!CONSP (tail))
break;
elt = XCAR (tail);
eltstring = CONSP (elt) ? XCAR (elt) : elt;
tail = XCDR (tail);
}
else if (type == obarray_table)
{
if (!EQ (bucket, zero))
{
if (!SYMBOLP (bucket))
error ("Bad data in guts of obarray");
elt = bucket;
eltstring = elt;
if (XSYMBOL (bucket)->u.s.next)
XSETSYMBOL (bucket, XSYMBOL (bucket)->u.s.next);
else
XSETFASTINT (bucket, 0);
}
else if (++idx >= obsize)
break;
else
{
bucket = AREF (collection, idx);
continue;
}
}
else /* if (type == hash_table) */
{
while (idx < HASH_TABLE_SIZE (XHASH_TABLE (collection))
&& BASE_EQ (HASH_KEY (XHASH_TABLE (collection), idx),
Qunbound))
idx++;
if (idx >= HASH_TABLE_SIZE (XHASH_TABLE (collection)))
break;
else
elt = eltstring = HASH_KEY (XHASH_TABLE (collection), idx++);
}
/* Is this element a possible completion? */
if (SYMBOLP (eltstring))
eltstring = Fsymbol_name (eltstring);
if (STRINGP (eltstring)
&& SCHARS (string) <= SCHARS (eltstring)
&& (tem = Fcompare_strings (eltstring, zero,
make_fixnum (SCHARS (string)),
string, zero, Qnil,
completion_ignore_case ? Qt : Qnil),
EQ (Qt, tem)))
{
/* Ignore this element if it fails to match all the regexps. */
if (!match_regexps (eltstring, Vcompletion_regexp_list,
completion_ignore_case))
continue;
/* Ignore this element if there is a predicate
and the predicate doesn't like it. */
if (!NILP (predicate))
{
if (EQ (predicate, Qcommandp))
tem = Fcommandp (elt, Qnil);
else
{
tem = (type == hash_table
? call2 (predicate, elt,
HASH_VALUE (XHASH_TABLE (collection),
idx - 1))
: call1 (predicate, elt));
}
if (NILP (tem)) continue;
}
/* Update computation of how much all possible completions match */
if (NILP (bestmatch))
{
matchcount = 1;
bestmatch = eltstring;
bestmatchsize = SCHARS (eltstring);
}
else
{
compare = min (bestmatchsize, SCHARS (eltstring));
Lisp_Object lcompare = make_fixnum (compare);
tem = Fcompare_strings (bestmatch, zero, lcompare,
eltstring, zero, lcompare,
completion_ignore_case ? Qt : Qnil);
matchsize = EQ (tem, Qt) ? compare : eabs (XFIXNUM (tem)) - 1;
Lisp_Object old_bestmatch = bestmatch;
if (completion_ignore_case)
{
/* If this is an exact match except for case,
use it as the best match rather than one that is not an
exact match. This way, we get the case pattern
of the actual match. */
if ((matchsize == SCHARS (eltstring)
&& matchsize < SCHARS (bestmatch))
||
/* If there is more than one exact match ignoring case,
and one of them is exact including case,
prefer that one. */
/* If there is no exact match ignoring case,
prefer a match that does not change the case
of the input. */
((matchsize == SCHARS (eltstring))
==
(matchsize == SCHARS (bestmatch))
&& (tem = Fcompare_strings (eltstring, zero,
make_fixnum (SCHARS (string)),
string, zero,
Qnil,
Qnil),
EQ (Qt, tem))
&& (tem = Fcompare_strings (bestmatch, zero,
make_fixnum (SCHARS (string)),
string, zero,
Qnil,
Qnil),
! EQ (Qt, tem))))
bestmatch = eltstring;
}
if (bestmatchsize != SCHARS (eltstring)
|| bestmatchsize != matchsize
|| (completion_ignore_case
&& !BASE_EQ (Fcompare_strings (old_bestmatch, zero,
lcompare, eltstring, zero,
lcompare, Qnil),
Qt)))
/* Don't count the same string multiple times. */
matchcount += matchcount <= 1;
bestmatchsize = matchsize;
if (matchsize <= SCHARS (string)
/* If completion-ignore-case is non-nil, don't
short-circuit because we want to find the best
possible match *including* case differences. */
&& !completion_ignore_case
&& matchcount > 1)
/* No need to look any further. */
break;
}
}
}
if (NILP (bestmatch))
return Qnil; /* No completions found. */
/* If we are ignoring case, and there is no exact match,
and no additional text was supplied,
don't change the case of what the user typed. */
if (completion_ignore_case && bestmatchsize == SCHARS (string)
&& SCHARS (bestmatch) > bestmatchsize)
return string;
/* Return t if the supplied string is an exact match (counting case);
it does not require any change to be made. */
if (matchcount == 1 && !NILP (Fequal (bestmatch, string)))
return Qt;
XSETFASTINT (zero, 0); /* Else extract the part in which */
XSETFASTINT (end, bestmatchsize); /* all completions agree. */
return Fsubstring (bestmatch, zero, end);
}