51 lines
51 KiB
HTML
51 lines
51 KiB
HTML
|
<!doctype html>
|
|||
|
|
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-chap-17/bh-d-dictionary/merge_function" data-has-hydrated="false">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="UTF-8">
|
|||
|
|
<meta name="generator" content="Docusaurus v3.0.1">
|
|||
|
|
<title data-rh="true">merge | Common Lisp (New) Language Reference</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://lisp-docs.github.io/cl-language-reference/img/1024px-Lisp_logo.svg.png"><meta data-rh="true" name="twitter:image" content="https://lisp-docs.github.io/cl-language-reference/img/1024px-Lisp_logo.svg.png"><meta data-rh="true" property="og:url" content="https://lisp-docs.github.io/cl-language-reference/chap-17/bh-d-dictionary/merge_function"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="google-site-verification" content="Vzaw013_bfdKeUVG89Ch3W1zC9_vH9ID2dPB9Dz0vr0"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="merge | Common Lisp (New) Language Reference"><meta data-rh="true" name="description" content="Expanded Reference: merge"><meta data-rh="true" property="og:description" content="Expanded Reference: merge"><link data-rh="true" rel="icon" href="../../img/favicon.ico"><link data-rh="true" rel="canonical" href="merge_function.html"><link data-rh="true" rel="alternate" href="merge_function.html" hreflang="en"><link data-rh="true" rel="alternate" href="merge_function.html" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://C1F2Q5VM6X-dsn.algolia.net" crossorigin="anonymous"><link rel="preconnect" href="https://www.google-analytics.com">
|
|||
|
|
<link rel="preconnect" href="https://www.googletagmanager.com">
|
|||
|
|
<script async src="https://www.googletagmanager.com/gtag/js?id=G-8TJCE4NSF8"></script>
|
|||
|
|
<script>function gtag(){dataLayer.push(arguments)}window.dataLayer=window.dataLayer||[],gtag("js",new Date),gtag("config","G-8TJCE4NSF8",{})</script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml" title="Common Lisp (New) Language Reference" href="../../opensearch.xml"><link rel="stylesheet" href="../../assets/css/styles.f13b59fe.css">
|
|||
|
|
<script src="../../assets/js/runtime~main.02699c25.js" defer="defer"></script>
|
|||
|
|
<script src="../../assets/js/main.4f0a7a76.js" defer="defer"></script>
|
|||
|
|
</head>
|
|||
|
|
<body class="navigation-with-keyboard">
|
|||
|
|
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return localStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"light")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="merge_function.html#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a href="../../../index.html" target="_blank" rel="noopener noreferrer" class="navbar__brand"><div class="navbar__logo"><img src="../../img/logo.svg" alt="Lisp Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="../../img/logo.svg" alt="Lisp Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">Common Lisp Docs</b></a><a href="../../../docs/tutorial/index.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Tutorial</a><a href="../../index.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Technical Reference</a><a href="../../../docs/whylisp.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Why Lisp?</a><a href="../../../docs/howto.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Guides</a></div><div class="navbar__items navbar__items--right"><a href="../../../docs/contribute.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Contribute!</a><a href="../../../docs/help.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Getting Help</a><a href="../../../docs/about.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">About</a><a href="../../../blog.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Blog</a><a href="https://github.com/lisp-docs" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.
|
|||
|
|
<!-- -->
|
|||
|
|
<!-- -->
|
|||
|
|
<p><strong>merge</strong> <span><i>Function</i></span></p>
|
|||
|
|
<p><strong>Syntax:</strong></p>
|
|||
|
|
<p><span><b>merge</b></span> <em>result-type sequence-1 sequence-2 predicate</em> &key <em>key → result-sequence</em></p>
|
|||
|
|
<p><strong>Arguments and Values:</strong></p>
|
|||
|
|
<p><em>result-type</em>—a <span><b>sequence</b></span> <span><i>type specifier</i></span> .</p>
|
|||
|
|
<p><em>sequence-1</em>—a <em>sequence</em>.</p>
|
|||
|
|
<p><em>sequence-2</em>—a <em>sequence</em>.</p>
|
|||
|
|
<p><span><i>predicate</i></span>—a <span><i>designator</i></span> for a <span><i>function</i></span> of two arguments that returns a <span><i>generalized boolean</i></span>. <span><i>key</i></span>—a <span><i>designator</i></span> for a <span><i>function</i></span> of one argument, or <span><b>nil</b></span>.</p>
|
|||
|
|
<p><em>result-sequence</em>—a <span><i>proper sequence</i></span> of <em>type result-type</em>.</p>
|
|||
|
|
<span><b>merge</b></span>
|
|||
|
|
<p><strong>Description:</strong></p>
|
|||
|
|
<p>Destructively merges <em>sequence-1</em> with <em>sequence-2</em> according to an order determined by the <span><i>predicate</i></span>. <span><b>merge</b></span> determines the relationship between two elements by giving keys extracted from the sequence elements to the <span><i>predicate</i></span>.</p>
|
|||
|
|
<p>The first argument to the <span><i>predicate</i></span> function is an element of <em>sequence-1</em> as returned by the <span><i>key</i></span> (if supplied); the second argument is an element of <em>sequence-2</em> as returned by the <span><i>key</i></span> (if supplied). <span><i>Predicate</i></span> should return <span><i>true</i></span> if and only if its first argument is strictly less than the second (in some appropriate sense). If the first argument is greater than or equal to the second (in the appropriate sense), then <span><i>predicate</i></span> should return <span><i>false</i></span>. <span><b>merge</b></span> considers two elements x and y to be equal if (funcall predicate x y) and (funcall predicate y x) both <em>yield false</em>.</p>
|
|||
|
|
<p>The argument to the <span><i>key</i></span> is the <em>sequence</em> element. Typically, the return value of the <span><i>key</i></span> becomes the argument to <span><i>predicate</i></span>. If <span><i>key</i></span> is not supplied or <span><b>nil</b></span>, the sequence element itself is used. The <span><i>key</i></span> may be executed more than once for each <em>sequence element</em>, and its side effects may occur in any order.</p>
|
|||
|
|
<p>If <span><i>key</i></span> and <span><i>predicate</i></span> return, then the merging operation will terminate. The result of merging two <em>sequences</em> x and y is a new <em>sequence</em> of type <em>result-type</em> z, such that the length of z is the sum of the lengths of x and y, and z contains all the elements of x and y. If x1 and x2 are two elements of x, and x1 precedes x2 in x, then x1 precedes x2 in z, and similarly for elements of y. In short, z is an interleaving of x and y.</p>
|
|||
|
|
<p>If x and y were correctly sorted according to the <span><i>predicate</i></span>, then z will also be correctly sorted. If x or y is not so sorted, then z will not be sorted, but will nevertheless be an interleaving of x and y.</p>
|
|||
|
|
<p>The merging operation is guaranteed stable; if two or more elements are considered equal by the <span><i>predicate</i></span>, then the elements from <em>sequence-1</em> will precede those from <em>sequence-2</em> in the result.</p>
|
|||
|
|
<p><em>sequence-1</em> and/or <em>sequence-2</em> may be destroyed.</p>
|
|||
|
|
<p>If the <em>result-type</em> is a <span><i>subtype</i></span> of <span><b>list</b></span>, the result will be a <span><i>list</i></span>.</p>
|
|||
|
|
<p>If the <em>result-type</em> is a <span><i>subtype</i></span> of <span><b>vector</b></span>, then if the implementation can determine the element type specified for the <em>result-type</em>, the element type of the resulting array is the result of <em>upgrading</em> that element type; or, if the implementation can determine that the element type is unspecified (or *), the element type of the resulting array is <span><b>t</b></span>; otherwise, an error is signaled.</p>
|
|||
|
|
<p><strong>Examples:</strong></p>
|
|||
|
|
<div class="language-lisp codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-lisp codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">(</span><span class="token keyword" style="color:#00009f">setq</span><span class="token plain"> test1 </span><span class="token punctuation" style="color:#393A34">(</span><span class="token car">list</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">3</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">4</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">6</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">7</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">(</span><span class="token keyword" style="color:#00009f">setq</span><span class="token plain"> test2 </span><span class="token punctuation" style="color:#393A34">(</span><span class="token car">list</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">5</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">8</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">(</span><span class="token car">merge</span><span class="token plain"> ’list test1 test2 #’<</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> → </span><span class="token punctuation" style="color:#393A34">(</span><span class="token number" style="color:#36acaa">1</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">3</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">4</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">5</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">6</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">7</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">8</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">(</span><span class="token keyword" style="color:#00009f">setq</span><span class="token plain"> test1 </span><span class="token punctuation" style="color:#393A34">(</span><span class="token car">copy-seq</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"BOY"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">(</span><span class="token keyword" style="color:#00009f">setq</span><span class="token plain"> tes
|
|||
|
|
<p><strong>Exceptional Situations:</strong></p>
|
|||
|
|
<p>An error must be signaled if the <em>result-type</em> is neither a <span><i>recognizable subtype</i></span> of <span><b>list</b></span>, nor a <span><i>recognizable subtype</i></span> of <span><b>vector</b></span>.</p>
|
|||
|
|
<p>An error of <span><i>type</i></span> <span><b>type-error</b></span> should be signaled if <em>result-type</em> specifies the number of elements and the sum of the lengths of <em>sequence-1</em> and <em>sequence-2</em> is different from that number.</p>
|
|||
|
|
<p><strong>See Also:</strong></p>
|
|||
|
|
<p><span><b>sort</b></span>, <span><b>stable-sort</b></span>, Section 3.2.1 (Compiler Terminology), Section 3.6 (Traversal Rules and Side Effects)</p>
|
|||
|
|
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="expanded-reference-merge">Expanded Reference: merge<a href="merge_function.html#expanded-reference-merge" class="hash-link" aria-label="Direct link to Expanded Reference: merge" title="Direct link to Expanded Reference: merge"></a></h2>
|
|||
|
|
<div class="theme-admonition theme-admonition-tip admonition_xJq3 alert alert--success"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_BuS1"><p>TODO: Please contribute to this page by adding explanations and examples</p></div></div>
|
|||
|
|
<div class="language-lisp codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-lisp codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">(</span><span class="token car">merge</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">)</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/lisp-docs/cl-language-reference/tree/main/docs/chap-17/bh-d-dictionary/merge_function.md" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"><span class="theme-last-updated">Last updated<!-- --> by <b>daninus14</b></span></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="map_function.html"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">map</div></a><a class="pagination-nav__link pagination-nav__link--next" href="mismatch_function.html"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">mismatch</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="merge_function.html#expanded-reference-merge" class="table-of-contents__link toc-highlight">Expanded Reference: merge</a></li></ul></div></div></div></div></main></div></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Docs</div><ul class="footer__items clean-list"><li class="footer__item"><a href="../../../docs/tutorial.html" target="_blank" rel="noopener noreferrer" class="footer__link-item">Common Lisp Tutorial</a></li><li class="footer__item"><a href="../../index.html" target="_blank" rel="noopener noreferrer" class="footer__link-item">Common Lisp Technical Reference</a></li><li class="footer__item"><a href="../../../docs/help.html" target="_blank" rel="noopener noreferrer" class="footer__link-item">Help</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://stackoverflow.com/questions/tagged/common-lisp" target="_blank" rel="noopener noreferrer" class="footer__link-item">Stack Overflow<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://discord.gg/hhk46CE" target="_blank" rel="noopener noreferrer" class="footer__link-
|
|||
|
|
</body>
|
|||
|
|
</html>
|