Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +"),i.setHtml(f),i.show(),t._signal("showGutterTooltip",i),t.on("mousewheel",c);if(e.$tooltipFollowsMouse)h(u);else{var p=u.domEvent.target,d=p.getBoundingClientRect(),v=i.getElement().style;v.left=d.right+"px",v.top=d.bottom+"px"}}function c(){o&&(o=clearTimeout(o)),f&&(i.hide(),f=null,t._signal("hideGutterTooltip",i),t.removeEventListener("mousewheel",c))}function h(e){i.setPosition(e.x,e.y)}var t=e.editor,n=t.renderer.$gutterLayer,i=new a(t.container);e.editor.setDefaultHandler("guttermousedown",function(r){if(!t.isFocused()||r.getButton()!=0)return;var i=n.getRegion(r);if(i=="foldWidgets")return;var s=r.getDocumentPosition().row,o=t.session.selection;if(r.getShiftKey())o.selectTo(s,0);else{if(r.domEvent.detail==2)return t.selectAll(),r.preventDefault();e.$clickSelection=t.selection.getLineRange(s)}return e.setState("selectByLines"),e.captureMouse(r),r.preventDefault()});var o,u,f;e.editor.setDefaultHandler("guttermousemove",function(t){var n=t.domEvent.target||t.domEvent.srcElement;if(r.hasCssClass(n,"ace_fold-widget"))return c();f&&e.$tooltipFollowsMouse&&h(t),u=t;if(o)return;o=setTimeout(function(){o=null,u&&!e.isMousePressed?l():c()},50)}),s.addListener(t.renderer.$gutter,"mouseout",function(e){u=null;if(!f||o)return;o=setTimeout(function(){o=null,c()},50)}),t.on("changeSession",c)}function a(e){o.call(this,e)}var r=e("../lib/dom"),i=e("../lib/oop"),s=e("../lib/event"),o=e("../tooltip").Tooltip;i.inherits(a,o),function(){this.setPosition=function(e,t){var n=window.innerWidth||document.documentElement.clientWidth,r=window.innerHeight||document.documentElement.clientHeight,i=this.getWidth(),s=this.getHeight();e+=15,t+=15,e+i>n&&(e-=e+i-n),t+s>r&&(t-=20+s),o.prototype.setPosition.call(this,e,t)}}.call(a.prototype),t.GutterHandler=u}),ace.define("ace/mouse/mouse_event",["require","exports","module","ace/lib/event","ace/lib/useragent"],function(e,t,n){"use strict";var r=e("../lib/event"),i=e("../lib/useragent"),s=t.MouseEvent=function(e,t){this.domEvent=e,this.editor=t,this.x=this.clientX=e.clientX,this.y=this.clientY=e.clientY,this.$pos=null,this.$inSelection=null,this.propagationStopped=!1,this.defaultPrevented=!1};(function(){this.stopPropagation=function(){r.stopPropagation(this.domEvent),this.propagationStopped=!0},this.preventDefault=function(){r.preventDefault(this.domEvent),this.defaultPrevented=!0},this.stop=function(){this.stopPropagation(),this.preventDefault()},this.getDocumentPosition=function(){return this.$pos?this.$pos:(this.$pos=this.editor.renderer.screenToTextCoordinates(this.clientX,this.clientY),this.$pos)},this.inSelection=function(){if(this.$inSelection!==null)return this.$inSelection;var e=this.editor,t=e.getSelectionRange();if(t.isEmpty())this.$inSelection=!1;else{var n=this.getDocumentPosition();this.$inSelection=t.contains(n.row,n.column)}return this.$inSelection},this.getButton=function(){return r.getButton(this.domEvent)},this.getShiftKey=function(){return this.domEvent.shiftKey},this.getAccelKey=i.isMac?function(){return this.domEvent.metaKey}:function(){return this.domEvent.ctrlKey}}).call(s.prototype)}),ace.define("ace/mouse/dragdrop_handler",["require","exports","module","ace/lib/dom","ace/lib/event","ace/lib/useragent"],function(e,t,n){"use strict";function f(e){function T(e,n){var r=Date.now(),i=!n||e.row!=n.row,s=!n||e.column!=n.column;if(!S||i||s)t.moveCursorToPosition(e),S=r,x={x:p,y:d};else{var o=l(x.x,x.y,p,d);o>a?S=null:r-S>=u&&(t.renderer.scrollCursorIntoView(),S=null)}}function N(e,n){var r=Date.now(),i=t.renderer.layerConfig.lineHeight,s=t.renderer.layerConfig.characterWidth,u=t.renderer.scroller.getBoundingClientRect(),a={x:{left:p-u.left,right:u.right-p},y:{top:d-u.top,bottom:u.bottom-d}},f=Math.min(a.x.left,a.x.right),l=Math.min(a.y.top,a.y.bottom),c={row:e.row,column:e.column};f/s<=2&&(c.column+=a.x.left
"),p.appendChild(i.createElement("div"));var m=function(e,t,n){if(t===0&&(n==="esc"||n==="return"))return h.destroy(),{command:"null"}};h.destroy=function(){if(e.$mouseHandler.isMousePressed)return;e.keyBinding.removeKeyboardHandler(m),n.widgetManager.removeLineWidget(h),e.off("changeSelection",h.destroy),e.off("changeSession",h.destroy),e.off("mouseup",h.destroy),e.off("change",h.destroy)},e.keyBinding.addKeyboardHandler(m),e.on("changeSelection",h.destroy),e.on("changeSession",h.destroy),e.on("mouseup",h.destroy),e.on("change",h.destroy),e.session.widgetManager.addLineWidget(h),h.el.onmousedown=e.focus.bind(e),e.renderer.scrollCursorIntoView(null,.5,{bottom:h.el.offsetHeight})},i.importCssString(" .error_widget_wrapper { background: inherit; color: inherit; border:none } .error_widget { border-top: solid 2px; border-bottom: solid 2px; margin: 5px 0; padding: 10px 40px; white-space: pre-wrap; } .error_widget.ace_error, .error_widget_arrow.ace_error{ border-color: #ff5a5a } .error_widget.ace_warning, .error_widget_arrow.ace_warning{ border-color: #F1D817 } .error_widget.ace_info, .error_widget_arrow.ace_info{ border-color: #5a5a5a } .error_widget.ace_ok, .error_widget_arrow.ace_ok{ border-color: #5aaa5a } .error_widget_arrow { position: absolute; border: solid 5px; border-top-color: transparent!important; border-right-color: transparent!important; border-left-color: transparent!important; top: -5px; }","")}),ace.define("ace/ace",["require","exports","module","ace/lib/fixoldbrowsers","ace/lib/dom","ace/lib/event","ace/range","ace/editor","ace/edit_session","ace/undomanager","ace/virtual_renderer","ace/worker/worker_client","ace/keyboard/hash_handler","ace/placeholder","ace/multi_select","ace/mode/folding/fold_mode","ace/theme/textmate","ace/ext/error_marker","ace/config"],function(e,t,n){"use strict";e("./lib/fixoldbrowsers");var r=e("./lib/dom"),i=e("./lib/event"),s=e("./range").Range,o=e("./editor").Editor,u=e("./edit_session").EditSession,a=e("./undomanager").UndoManager,f=e("./virtual_renderer").VirtualRenderer;e("./worker/worker_client"),e("./keyboard/hash_handler"),e("./placeholder"),e("./multi_select"),e("./mode/folding/fold_mode"),e("./theme/textmate"),e("./ext/error_marker"),t.config=e("./config"),t.require=e,typeof define=="function"&&(t.define=define),t.edit=function(e,n){if(typeof e=="string"){var s=e;e=document.getElementById(s);if(!e)throw new Error("ace.edit can't find div #"+s)}if(e&&e.env&&e.env.editor instanceof o)return e.env.editor;var u="";if(e&&/input|textarea/i.test(e.tagName)){var a=e;u=a.value,e=r.createElement("pre"),a.parentNode.replaceChild(e,a)}else e&&(u=e.textContent,e.innerHTML="");var l=t.createEditSession(u),c=new o(new f(e),l,n),h={document:l,editor:c,onResize:c.resize.bind(c,null)};return a&&(h.textarea=a),i.addListener(window,"resize",h.onResize),c.on("destroy",function(){i.removeListener(window,"resize",h.onResize),h.editor.container.env=null}),c.container.env=c.env=h,c},t.createEditSession=function(e,t){var n=new u(e,t);return n.setUndoManager(new a),n},t.Range=s,t.Editor=o,t.EditSession=u,t.UndoManager=a,t.VirtualRenderer=f,t.version="1.4.4"}); (function() { + ace.require(["ace/ace"], function(a) { + if (a) { + a.config.init(true); + a.define = ace.define; + } + if (!window.ace) + window.ace = a; + for (var key in a) if (a.hasOwnProperty(key)) + window.ace[key] = a[key]; + window.ace["default"] = window.ace; + if (typeof module == "object" && typeof exports == "object" && module) { + module.exports = window.ace; + } + }); + })(); diff --git a/ayu-highlight.css b/ayu-highlight.css new file mode 100644 index 00000000..32c94322 --- /dev/null +++ b/ayu-highlight.css @@ -0,0 +1,78 @@ +/* +Based off of the Ayu theme +Original by Dempfi (https://github.com/dempfi/ayu) +*/ + +.hljs { + display: block; + overflow-x: auto; + background: #191f26; + color: #e6e1cf; +} + +.hljs-comment, +.hljs-quote { + color: #5c6773; + font-style: italic; +} + +.hljs-variable, +.hljs-template-variable, +.hljs-attribute, +.hljs-attr, +.hljs-regexp, +.hljs-link, +.hljs-selector-id, +.hljs-selector-class { + color: #ff7733; +} + +.hljs-number, +.hljs-meta, +.hljs-builtin-name, +.hljs-literal, +.hljs-type, +.hljs-params { + color: #ffee99; +} + +.hljs-string, +.hljs-bullet { + color: #b8cc52; +} + +.hljs-title, +.hljs-built_in, +.hljs-section { + color: #ffb454; +} + +.hljs-keyword, +.hljs-selector-tag, +.hljs-symbol { + color: #ff7733; +} + +.hljs-name { + color: #36a3d9; +} + +.hljs-tag { + color: #00568d; +} + +.hljs-emphasis { + font-style: italic; +} + +.hljs-strong { + font-weight: bold; +} + +.hljs-addition { + color: #91b362; +} + +.hljs-deletion { + color: #d96c75; +} diff --git a/book.js b/book.js new file mode 100644 index 00000000..aa12e7ec --- /dev/null +++ b/book.js @@ -0,0 +1,697 @@ +"use strict"; + +// Fix back button cache problem +window.onunload = function () { }; + +// Global variable, shared between modules +function playground_text(playground, hidden = true) { + let code_block = playground.querySelector("code"); + + if (window.ace && code_block.classList.contains("editable")) { + let editor = window.ace.edit(code_block); + return editor.getValue(); + } else if (hidden) { + return code_block.textContent; + } else { + return code_block.innerText; + } +} + +(function codeSnippets() { + function fetch_with_timeout(url, options, timeout = 6000) { + return Promise.race([ + fetch(url, options), + new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout)) + ]); + } + + var playgrounds = Array.from(document.querySelectorAll(".playground")); + if (playgrounds.length > 0) { + fetch_with_timeout("https://play.rust-lang.org/meta/crates", { + headers: { + 'Content-Type': "application/json", + }, + method: 'POST', + mode: 'cors', + }) + .then(response => response.json()) + .then(response => { + // get list of crates available in the rust playground + let playground_crates = response.crates.map(item => item["id"]); + playgrounds.forEach(block => handle_crate_list_update(block, playground_crates)); + }); + } + + function handle_crate_list_update(playground_block, playground_crates) { + // update the play buttons after receiving the response + update_play_button(playground_block, playground_crates); + + // and install on change listener to dynamically update ACE editors + if (window.ace) { + let code_block = playground_block.querySelector("code"); + if (code_block.classList.contains("editable")) { + let editor = window.ace.edit(code_block); + editor.addEventListener("change", function (e) { + update_play_button(playground_block, playground_crates); + }); + // add Ctrl-Enter command to execute rust code + editor.commands.addCommand({ + name: "run", + bindKey: { + win: "Ctrl-Enter", + mac: "Ctrl-Enter" + }, + exec: _editor => run_rust_code(playground_block) + }); + } + } + } + + // updates the visibility of play button based on `no_run` class and + // used crates vs ones available on https://play.rust-lang.org + function update_play_button(pre_block, playground_crates) { + var play_button = pre_block.querySelector(".play-button"); + + // skip if code is `no_run` + if (pre_block.querySelector('code').classList.contains("no_run")) { + play_button.classList.add("hidden"); + return; + } + + // get list of `extern crate`'s from snippet + var txt = playground_text(pre_block); + var re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g; + var snippet_crates = []; + var item; + while (item = re.exec(txt)) { + snippet_crates.push(item[1]); + } + + // check if all used crates are available on play.rust-lang.org + var all_available = snippet_crates.every(function (elem) { + return playground_crates.indexOf(elem) > -1; + }); + + if (all_available) { + play_button.classList.remove("hidden"); + } else { + play_button.classList.add("hidden"); + } + } + + function run_rust_code(code_block) { + var result_block = code_block.querySelector(".result"); + if (!result_block) { + result_block = document.createElement('code'); + result_block.className = 'result hljs language-bash'; + + code_block.append(result_block); + } + + let text = playground_text(code_block); + let classes = code_block.querySelector('code').classList; + let edition = "2015"; + if(classes.contains("edition2018")) { + edition = "2018"; + } else if(classes.contains("edition2021")) { + edition = "2021"; + } + var params = { + version: "stable", + optimize: "0", + code: text, + edition: edition + }; + + if (text.indexOf("#![feature") !== -1) { + params.version = "nightly"; + } + + result_block.innerText = "Running..."; + + fetch_with_timeout("https://play.rust-lang.org/evaluate.json", { + headers: { + 'Content-Type': "application/json", + }, + method: 'POST', + mode: 'cors', + body: JSON.stringify(params) + }) + .then(response => response.json()) + .then(response => { + if (response.result.trim() === '') { + result_block.innerText = "No output"; + result_block.classList.add("result-no-output"); + } else { + result_block.innerText = response.result; + result_block.classList.remove("result-no-output"); + } + }) + .catch(error => result_block.innerText = "Playground Communication: " + error.message); + } + + // Syntax highlighting Configuration + hljs.configure({ + tabReplace: ' ', // 4 spaces + languages: [], // Languages used for auto-detection + }); + + let code_nodes = Array + .from(document.querySelectorAll('code')) + // Don't highlight `inline code` blocks in headers. + .filter(function (node) {return !node.parentElement.classList.contains("header"); }); + + if (window.ace) { + // language-rust class needs to be removed for editable + // blocks or highlightjs will capture events + code_nodes + .filter(function (node) {return node.classList.contains("editable"); }) + .forEach(function (block) { block.classList.remove('language-rust'); }); + + code_nodes + .filter(function (node) {return !node.classList.contains("editable"); }) + .forEach(function (block) { hljs.highlightBlock(block); }); + } else { + code_nodes.forEach(function (block) { hljs.highlightBlock(block); }); + } + + // Adding the hljs class gives code blocks the color css + // even if highlighting doesn't apply + code_nodes.forEach(function (block) { block.classList.add('hljs'); }); + + Array.from(document.querySelectorAll("code.hljs")).forEach(function (block) { + + var lines = Array.from(block.querySelectorAll('.boring')); + // If no lines were hidden, return + if (!lines.length) { return; } + block.classList.add("hide-boring"); + + var buttons = document.createElement('div'); + buttons.className = 'buttons'; + buttons.innerHTML = ""; + + // add expand button + var pre_block = block.parentNode; + pre_block.insertBefore(buttons, pre_block.firstChild); + + pre_block.querySelector('.buttons').addEventListener('click', function (e) { + if (e.target.classList.contains('fa-eye')) { + e.target.classList.remove('fa-eye'); + e.target.classList.add('fa-eye-slash'); + e.target.title = 'Hide lines'; + e.target.setAttribute('aria-label', e.target.title); + + block.classList.remove('hide-boring'); + } else if (e.target.classList.contains('fa-eye-slash')) { + e.target.classList.remove('fa-eye-slash'); + e.target.classList.add('fa-eye'); + e.target.title = 'Show hidden lines'; + e.target.setAttribute('aria-label', e.target.title); + + block.classList.add('hide-boring'); + } + }); + }); + + if (window.playground_copyable) { + Array.from(document.querySelectorAll('pre code')).forEach(function (block) { + var pre_block = block.parentNode; + if (!pre_block.classList.contains('playground')) { + var buttons = pre_block.querySelector(".buttons"); + if (!buttons) { + buttons = document.createElement('div'); + buttons.className = 'buttons'; + pre_block.insertBefore(buttons, pre_block.firstChild); + } + + var clipButton = document.createElement('button'); + clipButton.className = 'fa fa-copy clip-button'; + clipButton.title = 'Copy to clipboard'; + clipButton.setAttribute('aria-label', clipButton.title); + clipButton.innerHTML = ''; + + buttons.insertBefore(clipButton, buttons.firstChild); + } + }); + } + + // Process playground code blocks + Array.from(document.querySelectorAll(".playground")).forEach(function (pre_block) { + // Add play button + var buttons = pre_block.querySelector(".buttons"); + if (!buttons) { + buttons = document.createElement('div'); + buttons.className = 'buttons'; + pre_block.insertBefore(buttons, pre_block.firstChild); + } + + var runCodeButton = document.createElement('button'); + runCodeButton.className = 'fa fa-play play-button'; + runCodeButton.hidden = true; + runCodeButton.title = 'Run this code'; + runCodeButton.setAttribute('aria-label', runCodeButton.title); + + buttons.insertBefore(runCodeButton, buttons.firstChild); + runCodeButton.addEventListener('click', function (e) { + run_rust_code(pre_block); + }); + + if (window.playground_copyable) { + var copyCodeClipboardButton = document.createElement('button'); + copyCodeClipboardButton.className = 'fa fa-copy clip-button'; + copyCodeClipboardButton.innerHTML = ''; + copyCodeClipboardButton.title = 'Copy to clipboard'; + copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title); + + buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild); + } + + let code_block = pre_block.querySelector("code"); + if (window.ace && code_block.classList.contains("editable")) { + var undoChangesButton = document.createElement('button'); + undoChangesButton.className = 'fa fa-history reset-button'; + undoChangesButton.title = 'Undo changes'; + undoChangesButton.setAttribute('aria-label', undoChangesButton.title); + + buttons.insertBefore(undoChangesButton, buttons.firstChild); + + undoChangesButton.addEventListener('click', function () { + let editor = window.ace.edit(code_block); + editor.setValue(editor.originalCode); + editor.clearSelection(); + }); + } + }); +})(); + +(function themes() { + var html = document.querySelector('html'); + var themeToggleButton = document.getElementById('theme-toggle'); + var themePopup = document.getElementById('theme-list'); + var themeColorMetaTag = document.querySelector('meta[name="theme-color"]'); + var stylesheets = { + ayuHighlight: document.querySelector("[href$='ayu-highlight.css']"), + tomorrowNight: document.querySelector("[href$='tomorrow-night.css']"), + highlight: document.querySelector("[href$='highlight.css']"), + }; + + function showThemes() { + themePopup.style.display = 'block'; + themeToggleButton.setAttribute('aria-expanded', true); + themePopup.querySelector("button#" + get_theme()).focus(); + } + + function updateThemeSelected() { + themePopup.querySelectorAll('.theme-selected').forEach(function (el) { + el.classList.remove('theme-selected'); + }); + themePopup.querySelector("button#" + get_theme()).classList.add('theme-selected'); + } + + function hideThemes() { + themePopup.style.display = 'none'; + themeToggleButton.setAttribute('aria-expanded', false); + themeToggleButton.focus(); + } + + function get_theme() { + var theme; + try { theme = localStorage.getItem('mdbook-theme'); } catch (e) { } + if (theme === null || theme === undefined) { + return default_theme; + } else { + return theme; + } + } + + function set_theme(theme, store = true) { + let ace_theme; + + if (theme == 'coal' || theme == 'navy') { + stylesheets.ayuHighlight.disabled = true; + stylesheets.tomorrowNight.disabled = false; + stylesheets.highlight.disabled = true; + + ace_theme = "ace/theme/tomorrow_night"; + } else if (theme == 'ayu') { + stylesheets.ayuHighlight.disabled = false; + stylesheets.tomorrowNight.disabled = true; + stylesheets.highlight.disabled = true; + ace_theme = "ace/theme/tomorrow_night"; + } else { + stylesheets.ayuHighlight.disabled = true; + stylesheets.tomorrowNight.disabled = true; + stylesheets.highlight.disabled = false; + ace_theme = "ace/theme/dawn"; + } + + setTimeout(function () { + themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor; + }, 1); + + if (window.ace && window.editors) { + window.editors.forEach(function (editor) { + editor.setTheme(ace_theme); + }); + } + + var previousTheme = get_theme(); + + if (store) { + try { localStorage.setItem('mdbook-theme', theme); } catch (e) { } + } + + html.classList.remove(previousTheme); + html.classList.add(theme); + updateThemeSelected(); + } + + // Set theme + var theme = get_theme(); + + set_theme(theme, false); + + themeToggleButton.addEventListener('click', function () { + if (themePopup.style.display === 'block') { + hideThemes(); + } else { + showThemes(); + } + }); + + themePopup.addEventListener('click', function (e) { + var theme; + if (e.target.className === "theme") { + theme = e.target.id; + } else if (e.target.parentElement.className === "theme") { + theme = e.target.parentElement.id; + } else { + return; + } + set_theme(theme); + }); + + themePopup.addEventListener('focusout', function(e) { + // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below) + if (!!e.relatedTarget && !themeToggleButton.contains(e.relatedTarget) && !themePopup.contains(e.relatedTarget)) { + hideThemes(); + } + }); + + // Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang/mdBook/issues/628 + document.addEventListener('click', function(e) { + if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) { + hideThemes(); + } + }); + + document.addEventListener('keydown', function (e) { + if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; } + if (!themePopup.contains(e.target)) { return; } + + switch (e.key) { + case 'Escape': + e.preventDefault(); + hideThemes(); + break; + case 'ArrowUp': + e.preventDefault(); + var li = document.activeElement.parentElement; + if (li && li.previousElementSibling) { + li.previousElementSibling.querySelector('button').focus(); + } + break; + case 'ArrowDown': + e.preventDefault(); + var li = document.activeElement.parentElement; + if (li && li.nextElementSibling) { + li.nextElementSibling.querySelector('button').focus(); + } + break; + case 'Home': + e.preventDefault(); + themePopup.querySelector('li:first-child button').focus(); + break; + case 'End': + e.preventDefault(); + themePopup.querySelector('li:last-child button').focus(); + break; + } + }); +})(); + +(function sidebar() { + var body = document.querySelector("body"); + var sidebar = document.getElementById("sidebar"); + var sidebarLinks = document.querySelectorAll('#sidebar a'); + var sidebarToggleButton = document.getElementById("sidebar-toggle"); + var sidebarResizeHandle = document.getElementById("sidebar-resize-handle"); + var firstContact = null; + + function showSidebar() { + body.classList.remove('sidebar-hidden') + body.classList.add('sidebar-visible'); + Array.from(sidebarLinks).forEach(function (link) { + link.setAttribute('tabIndex', 0); + }); + sidebarToggleButton.setAttribute('aria-expanded', true); + sidebar.setAttribute('aria-hidden', false); + try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { } + } + + + var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle'); + + function toggleSection(ev) { + ev.currentTarget.parentElement.classList.toggle('expanded'); + } + + Array.from(sidebarAnchorToggles).forEach(function (el) { + el.addEventListener('click', toggleSection); + }); + + function hideSidebar() { + body.classList.remove('sidebar-visible') + body.classList.add('sidebar-hidden'); + Array.from(sidebarLinks).forEach(function (link) { + link.setAttribute('tabIndex', -1); + }); + sidebarToggleButton.setAttribute('aria-expanded', false); + sidebar.setAttribute('aria-hidden', true); + try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { } + } + + // Toggle sidebar + sidebarToggleButton.addEventListener('click', function sidebarToggle() { + if (body.classList.contains("sidebar-hidden")) { + var current_width = parseInt( + document.documentElement.style.getPropertyValue('--sidebar-width'), 10); + if (current_width < 150) { + document.documentElement.style.setProperty('--sidebar-width', '150px'); + } + showSidebar(); + } else if (body.classList.contains("sidebar-visible")) { + hideSidebar(); + } else { + if (getComputedStyle(sidebar)['transform'] === 'none') { + hideSidebar(); + } else { + showSidebar(); + } + } + }); + + sidebarResizeHandle.addEventListener('mousedown', initResize, false); + + function initResize(e) { + window.addEventListener('mousemove', resize, false); + window.addEventListener('mouseup', stopResize, false); + body.classList.add('sidebar-resizing'); + } + function resize(e) { + var pos = (e.clientX - sidebar.offsetLeft); + if (pos < 20) { + hideSidebar(); + } else { + if (body.classList.contains("sidebar-hidden")) { + showSidebar(); + } + pos = Math.min(pos, window.innerWidth - 100); + document.documentElement.style.setProperty('--sidebar-width', pos + 'px'); + } + } + //on mouseup remove windows functions mousemove & mouseup + function stopResize(e) { + body.classList.remove('sidebar-resizing'); + window.removeEventListener('mousemove', resize, false); + window.removeEventListener('mouseup', stopResize, false); + } + + document.addEventListener('touchstart', function (e) { + firstContact = { + x: e.touches[0].clientX, + time: Date.now() + }; + }, { passive: true }); + + document.addEventListener('touchmove', function (e) { + if (!firstContact) + return; + + var curX = e.touches[0].clientX; + var xDiff = curX - firstContact.x, + tDiff = Date.now() - firstContact.time; + + if (tDiff < 250 && Math.abs(xDiff) >= 150) { + if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300)) + showSidebar(); + else if (xDiff < 0 && curX < 300) + hideSidebar(); + + firstContact = null; + } + }, { passive: true }); +})(); + +(function chapterNavigation() { + document.addEventListener('keydown', function (e) { + if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; } + if (window.search && window.search.hasFocus()) { return; } + var html = document.querySelector('html'); + + function next() { + var nextButton = document.querySelector('.nav-chapters.next'); + if (nextButton) { + window.location.href = nextButton.href; + } + } + function prev() { + var previousButton = document.querySelector('.nav-chapters.previous'); + if (previousButton) { + window.location.href = previousButton.href; + } + } + switch (e.key) { + case 'ArrowRight': + e.preventDefault(); + if (html.dir == 'rtl') { + prev(); + } else { + next(); + } + break; + case 'ArrowLeft': + e.preventDefault(); + if (html.dir == 'rtl') { + next(); + } else { + prev(); + } + break; + } + }); +})(); + +(function clipboard() { + var clipButtons = document.querySelectorAll('.clip-button'); + + function hideTooltip(elem) { + elem.firstChild.innerText = ""; + elem.className = 'fa fa-copy clip-button'; + } + + function showTooltip(elem, msg) { + elem.firstChild.innerText = msg; + elem.className = 'fa fa-copy tooltipped'; + } + + var clipboardSnippets = new ClipboardJS('.clip-button', { + text: function (trigger) { + hideTooltip(trigger); + let playground = trigger.closest("pre"); + return playground_text(playground, false); + } + }); + + Array.from(clipButtons).forEach(function (clipButton) { + clipButton.addEventListener('mouseout', function (e) { + hideTooltip(e.currentTarget); + }); + }); + + clipboardSnippets.on('success', function (e) { + e.clearSelection(); + showTooltip(e.trigger, "Copied!"); + }); + + clipboardSnippets.on('error', function (e) { + showTooltip(e.trigger, "Clipboard error!"); + }); +})(); + +(function scrollToTop () { + var menuTitle = document.querySelector('.menu-title'); + + menuTitle.addEventListener('click', function () { + document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' }); + }); +})(); + +(function controllMenu() { + var menu = document.getElementById('menu-bar'); + + (function controllPosition() { + var scrollTop = document.scrollingElement.scrollTop; + var prevScrollTop = scrollTop; + var minMenuY = -menu.clientHeight - 50; + // When the script loads, the page can be at any scroll (e.g. if you reforesh it). + menu.style.top = scrollTop + 'px'; + // Same as parseInt(menu.style.top.slice(0, -2), but faster + var topCache = menu.style.top.slice(0, -2); + menu.classList.remove('sticky'); + var stickyCache = false; // Same as menu.classList.contains('sticky'), but faster + document.addEventListener('scroll', function () { + scrollTop = Math.max(document.scrollingElement.scrollTop, 0); + // `null` means that it doesn't need to be updated + var nextSticky = null; + var nextTop = null; + var scrollDown = scrollTop > prevScrollTop; + var menuPosAbsoluteY = topCache - scrollTop; + if (scrollDown) { + nextSticky = false; + if (menuPosAbsoluteY > 0) { + nextTop = prevScrollTop; + } + } else { + if (menuPosAbsoluteY > 0) { + nextSticky = true; + } else if (menuPosAbsoluteY < minMenuY) { + nextTop = prevScrollTop + minMenuY; + } + } + if (nextSticky === true && stickyCache === false) { + menu.classList.add('sticky'); + stickyCache = true; + } else if (nextSticky === false && stickyCache === true) { + menu.classList.remove('sticky'); + stickyCache = false; + } + if (nextTop !== null) { + menu.style.top = nextTop + 'px'; + topCache = nextTop; + } + prevScrollTop = scrollTop; + }, { passive: true }); + })(); + (function controllBorder() { + function updateBorder() { + if (menu.offsetTop === 0) { + menu.classList.remove('bordered'); + } else { + menu.classList.add('bordered'); + } + } + updateBorder(); + document.addEventListener('scroll', updateBorder, { passive: true }); + })(); +})(); diff --git a/clipboard.min.js b/clipboard.min.js new file mode 100644 index 00000000..02c549e3 --- /dev/null +++ b/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.4 + * https://zenorocha.github.io/clipboard.js + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return function(n){var o={};function r(t){if(o[t])return o[t].exports;var e=o[t]={i:t,l:!1,exports:{}};return n[t].call(e.exports,e,e.exports,r),e.l=!0,e.exports}return r.m=n,r.c=o,r.d=function(t,e,n){r.o(t,e)||Object.defineProperty(t,e,{enumerable:!0,get:n})},r.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(t){var e=t&&t.__esModule?function(){return t.default}:function(){return t};return r.d(e,"a",e),e},r.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},r.p="",r(r.s=0)}([function(t,e,n){"use strict";var r="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},i=function(){function o(t,e){for(var n=0;n
List of all items
Structs
Redirecting to ../../../basis/list/struct.Stack.html...
+ + + \ No newline at end of file diff --git a/doc/basis/list/struct.Stack.html b/doc/basis/list/struct.Stack.html new file mode 100644 index 00000000..7384a8df --- /dev/null +++ b/doc/basis/list/struct.Stack.html @@ -0,0 +1,15 @@ +pub struct Stack<T> { /* private fields */ }Implementations§
Trait Implementations§
Auto Trait Implementations§
impl<T> Freeze for Stack<T>
impl<T> RefUnwindSafe for Stack<T>where
+ T: RefUnwindSafe,
impl<T> Send for Stack<T>where
+ T: Send,
impl<T> Sync for Stack<T>where
+ T: Sync,
impl<T> Unpin for Stack<T>
impl<T> UnwindSafe for Stack<T>where
+ T: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
List of all items
Functions
Function hello_world::hello
source · pub fn hello() -> &'static strCrate hello_world
source ·Functions§
Rustdoc help
BackList of all items
Structs
- Args
- HintArgs
- ListArgs
- RunArgs
- VerifyArgs
- WatchArgs
- exercise::CompiledExercise
- exercise::ContextLine
- exercise::Exercise
- exercise::ExerciseList
- exercise::ExerciseOutput
- exercise::FileHandle
Enums
Macros
Functions
- exercise::clean
- exercise::temp_file
- find_exercise
- main
- run::compile_and_run
- run::run
- rustc_exists
- spawn_watch_shell
- verify::compile
- verify::compile_and_run_interactively
- verify::compile_and_test
- verify::compile_only
- verify::prompt_for_completion
- verify::separator
- verify::test
- verify::verify
- watch
Constants
Enum rustlings::Subcommands
source · pub(crate) enum Subcommands {
+ Verify(VerifyArgs),
+ Watch(WatchArgs),
+ Run(RunArgs),
+ Hint(HintArgs),
+ List(ListArgs),
+}Variants§
Trait Implementations§
source§impl Debug for Subcommands
impl Debug for Subcommands
source§impl FromArgs for Subcommands
impl FromArgs for Subcommands
source§fn from_args(command_name: &[&str], args: &[&str]) -> Result<Self, EarlyExit>
fn from_args(command_name: &[&str], args: &[&str]) -> Result<Self, EarlyExit>
Construct the type from an input set of arguments. Read more
source§fn redact_arg_values(
+ command_name: &[&str],
+ args: &[&str],
+) -> Result<Vec<String>, EarlyExit>
fn redact_arg_values( + command_name: &[&str], + args: &[&str], +) -> Result<Vec<String>, EarlyExit>
Get a String with just the argument names, e.g., options, flags, subcommands, etc, but
+without the values of the options and arguments. This can be useful as a means to capture
+anonymous usage statistics without revealing the content entered by the end user. Read more
source§impl PartialEq for Subcommands
impl PartialEq for Subcommands
source§fn eq(&self, other: &Subcommands) -> bool
fn eq(&self, other: &Subcommands) -> bool
This method tests for
self and other values to be equal, and is used
+by ==.source§impl SubCommands for Subcommands
impl SubCommands for Subcommands
§fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
Get a list of commands that are discovered at runtime.
impl StructuralPartialEq for Subcommands
Auto Trait Implementations§
impl Freeze for Subcommands
impl RefUnwindSafe for Subcommands
impl Send for Subcommands
impl Sync for Subcommands
impl Unpin for Subcommands
impl UnwindSafe for Subcommands
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
Enum rustlings::WatchStatus
source · pub(crate) enum WatchStatus {
+ Finished,
+ Unfinished,
+}Variants§
Auto Trait Implementations§
impl Freeze for WatchStatus
impl RefUnwindSafe for WatchStatus
impl Send for WatchStatus
impl Sync for WatchStatus
impl Unpin for WatchStatus
impl UnwindSafe for WatchStatus
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
Constant rustlings::exercise::CLIPPY_CARGO_TOML_PATH
source · const CLIPPY_CARGO_TOML_PATH: &str = "./exercises/clippy/Cargo.toml";Constant rustlings::exercise::I_AM_DONE_REGEX
source · const I_AM_DONE_REGEX: &str = r"(?m)^\s*///?\s*I\s+AM\s+NOT\s+DONE";Constant rustlings::exercise::RUSTC_COLOR_ARGS
source · const RUSTC_COLOR_ARGS: &[&str];pub enum Mode {
+ Compile,
+ Test,
+ Clippy,
+}Variants§
Trait Implementations§
source§impl<'de> Deserialize<'de> for Mode
impl<'de> Deserialize<'de> for Mode
source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
+ __D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
+ __D: Deserializer<'de>,
Deserialize this value from the given Serde deserializer. Read more
impl Copy for Mode
Auto Trait Implementations§
impl Freeze for Mode
impl RefUnwindSafe for Mode
impl Send for Mode
impl Sync for Mode
impl Unpin for Mode
impl UnwindSafe for Mode
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> DeserializeOwned for Twhere
+ T: for<'de> Deserialize<'de>,
pub enum State {
+ Done,
+ Pending(Vec<ContextLine>),
+}Variants§
Done
Pending(Vec<ContextLine>)
Trait Implementations§
source§impl PartialEq for State
impl PartialEq for State
impl Eq for State
impl StructuralPartialEq for State
Auto Trait Implementations§
impl Freeze for State
impl RefUnwindSafe for State
impl Send for State
impl Sync for State
impl Unpin for State
impl UnwindSafe for State
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
Checks if this value is equivalent to the given key. Read more
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
Compare self to
key and return true if they are equal.Struct rustlings::exercise::CompiledExercise
source · pub struct CompiledExercise<'a> {
+ exercise: &'a Exercise,
+ _handle: FileHandle,
+}Fields§
§exercise: &'a Exercise§_handle: FileHandleImplementations§
source§impl<'a> CompiledExercise<'a>
impl<'a> CompiledExercise<'a>
pub fn run(&self) -> Result<ExerciseOutput, ExerciseOutput>
Auto Trait Implementations§
impl<'a> Freeze for CompiledExercise<'a>
impl<'a> RefUnwindSafe for CompiledExercise<'a>
impl<'a> Send for CompiledExercise<'a>
impl<'a> Sync for CompiledExercise<'a>
impl<'a> Unpin for CompiledExercise<'a>
impl<'a> UnwindSafe for CompiledExercise<'a>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
Struct rustlings::exercise::ContextLine
source · pub struct ContextLine {
+ pub line: String,
+ pub number: usize,
+ pub important: bool,
+}Fields§
§line: String§number: usize§important: boolTrait Implementations§
source§impl Debug for ContextLine
impl Debug for ContextLine
source§impl PartialEq for ContextLine
impl PartialEq for ContextLine
source§fn eq(&self, other: &ContextLine) -> bool
fn eq(&self, other: &ContextLine) -> bool
This method tests for
self and other values to be equal, and is used
+by ==.impl Eq for ContextLine
impl StructuralPartialEq for ContextLine
Auto Trait Implementations§
impl Freeze for ContextLine
impl RefUnwindSafe for ContextLine
impl Send for ContextLine
impl Sync for ContextLine
impl Unpin for ContextLine
impl UnwindSafe for ContextLine
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
Checks if this value is equivalent to the given key. Read more
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
Compare self to
key and return true if they are equal.pub struct Exercise {
+ pub name: String,
+ pub path: PathBuf,
+ pub mode: Mode,
+ pub hint: String,
+}Fields§
§name: String§path: PathBuf§mode: Mode§hint: StringImplementations§
source§impl Exercise
impl Exercise
pub fn compile(&self) -> Result<CompiledExercise<'_>, ExerciseOutput>
fn run(&self) -> Result<ExerciseOutput, ExerciseOutput>
pub fn state(&self) -> State
pub fn looks_done(&self) -> bool
Trait Implementations§
source§impl<'de> Deserialize<'de> for Exercise
impl<'de> Deserialize<'de> for Exercise
source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
+ __D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
+ __D: Deserializer<'de>,
Deserialize this value from the given Serde deserializer. Read more
Auto Trait Implementations§
impl Freeze for Exercise
impl RefUnwindSafe for Exercise
impl Send for Exercise
impl Sync for Exercise
impl Unpin for Exercise
impl UnwindSafe for Exercise
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> DeserializeOwned for Twhere
+ T: for<'de> Deserialize<'de>,
Struct rustlings::exercise::ExerciseList
source · pub struct ExerciseList {
+ pub exercises: Vec<Exercise>,
+}Fields§
§exercises: Vec<Exercise>Trait Implementations§
source§impl<'de> Deserialize<'de> for ExerciseList
impl<'de> Deserialize<'de> for ExerciseList
source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
+ __D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
+ __D: Deserializer<'de>,
Deserialize this value from the given Serde deserializer. Read more
Auto Trait Implementations§
impl Freeze for ExerciseList
impl RefUnwindSafe for ExerciseList
impl Send for ExerciseList
impl Sync for ExerciseList
impl Unpin for ExerciseList
impl UnwindSafe for ExerciseList
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> DeserializeOwned for Twhere
+ T: for<'de> Deserialize<'de>,
Struct rustlings::exercise::ExerciseOutput
source · pub struct ExerciseOutput {
+ pub stdout: String,
+ pub stderr: String,
+}Fields§
§stdout: String§stderr: StringTrait Implementations§
Auto Trait Implementations§
impl Freeze for ExerciseOutput
impl RefUnwindSafe for ExerciseOutput
impl Send for ExerciseOutput
impl Sync for ExerciseOutput
impl Unpin for ExerciseOutput
impl UnwindSafe for ExerciseOutput
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
Struct rustlings::exercise::FileHandle
source · struct FileHandle;Trait Implementations§
Auto Trait Implementations§
impl Freeze for FileHandle
impl RefUnwindSafe for FileHandle
impl Send for FileHandle
impl Sync for FileHandle
impl Unpin for FileHandle
impl UnwindSafe for FileHandle
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
Function rustlings::rustc_exists
source · pub(crate) fn rustc_exists() -> boolFunction rustlings::spawn_watch_shell
source · pub(crate) fn spawn_watch_shell(
+ failed_exercise_hint: &Arc<Mutex<Option<String>>>,
+ should_quit: Arc<AtomicBool>,
+)Modules§
Structs§
- Args 🔒Rustlings is a collection of small exercises to get you used to writing and reading Rust code
- HintArgs 🔒Returns a hint for the given exercise
- ListArgs 🔒Lists the exercises available in Rustlings
- RunArgs 🔒Runs/Tests a single exercise
- Verifies all exercises according to the recommended order
- Reruns
verifywhen files were edited
Enums§
Constants§
- VERSION 🔒
Functions§
pub(crate) struct Args {
+ pub(crate) nocapture: bool,
+ pub(crate) version: bool,
+ pub(crate) nested: Option<Subcommands>,
+}Expand description
Rustlings is a collection of small exercises to get you used to writing and reading Rust code
+Fields§
§nocapture: boolshow outputs from the test exercises
+version: boolshow the executable version
+nested: Option<Subcommands>Trait Implementations§
source§impl FromArgs for Args
impl FromArgs for Args
source§fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
Construct the type from an input set of arguments. Read more
source§fn redact_arg_values(
+ __cmd_name: &[&str],
+ __args: &[&str],
+) -> Result<Vec<String>, EarlyExit>
fn redact_arg_values( + __cmd_name: &[&str], + __args: &[&str], +) -> Result<Vec<String>, EarlyExit>
Get a String with just the argument names, e.g., options, flags, subcommands, etc, but
+without the values of the options and arguments. This can be useful as a means to capture
+anonymous usage statistics without revealing the content entered by the end user. Read more
source§impl PartialEq for Args
impl PartialEq for Args
impl StructuralPartialEq for Args
impl TopLevelCommand for Args
Auto Trait Implementations§
impl Freeze for Args
impl RefUnwindSafe for Args
impl Send for Args
impl Sync for Args
impl Unpin for Args
impl UnwindSafe for Args
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
pub(crate) struct HintArgs {
+ pub(crate) name: String,
+}Expand description
Returns a hint for the given exercise
+Fields§
§name: Stringthe name of the exercise
+Trait Implementations§
source§impl FromArgs for HintArgs
impl FromArgs for HintArgs
source§fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
Construct the type from an input set of arguments. Read more
source§fn redact_arg_values(
+ __cmd_name: &[&str],
+ __args: &[&str],
+) -> Result<Vec<String>, EarlyExit>
fn redact_arg_values( + __cmd_name: &[&str], + __args: &[&str], +) -> Result<Vec<String>, EarlyExit>
Get a String with just the argument names, e.g., options, flags, subcommands, etc, but
+without the values of the options and arguments. This can be useful as a means to capture
+anonymous usage statistics without revealing the content entered by the end user. Read more
source§impl PartialEq for HintArgs
impl PartialEq for HintArgs
impl StructuralPartialEq for HintArgs
Auto Trait Implementations§
impl Freeze for HintArgs
impl RefUnwindSafe for HintArgs
impl Send for HintArgs
impl Sync for HintArgs
impl Unpin for HintArgs
impl UnwindSafe for HintArgs
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
§impl<T> SubCommands for Twhere
+ T: SubCommand,
impl<T> SubCommands for Twhere
+ T: SubCommand,
§fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
Get a list of commands that are discovered at runtime.
pub(crate) struct ListArgs {
+ pub(crate) paths: bool,
+ pub(crate) names: bool,
+ pub(crate) filter: Option<String>,
+ pub(crate) unsolved: bool,
+ pub(crate) solved: bool,
+}Expand description
Lists the exercises available in Rustlings
+Fields§
§paths: boolshow only the paths of the exercises
+names: boolshow only the names of the exercises
+filter: Option<String>provide a string to match exercise names +comma separated patterns are acceptable
+unsolved: booldisplay only exercises not yet solved
+solved: booldisplay only exercises that have been solved
+Trait Implementations§
source§impl FromArgs for ListArgs
impl FromArgs for ListArgs
source§fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
Construct the type from an input set of arguments. Read more
source§fn redact_arg_values(
+ __cmd_name: &[&str],
+ __args: &[&str],
+) -> Result<Vec<String>, EarlyExit>
fn redact_arg_values( + __cmd_name: &[&str], + __args: &[&str], +) -> Result<Vec<String>, EarlyExit>
Get a String with just the argument names, e.g., options, flags, subcommands, etc, but
+without the values of the options and arguments. This can be useful as a means to capture
+anonymous usage statistics without revealing the content entered by the end user. Read more
source§impl PartialEq for ListArgs
impl PartialEq for ListArgs
impl StructuralPartialEq for ListArgs
Auto Trait Implementations§
impl Freeze for ListArgs
impl RefUnwindSafe for ListArgs
impl Send for ListArgs
impl Sync for ListArgs
impl Unpin for ListArgs
impl UnwindSafe for ListArgs
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
§impl<T> SubCommands for Twhere
+ T: SubCommand,
impl<T> SubCommands for Twhere
+ T: SubCommand,
§fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
Get a list of commands that are discovered at runtime.
pub(crate) struct RunArgs {
+ pub(crate) name: String,
+}Expand description
Runs/Tests a single exercise
+Fields§
§name: Stringthe name of the exercise
+Trait Implementations§
source§impl FromArgs for RunArgs
impl FromArgs for RunArgs
source§fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
Construct the type from an input set of arguments. Read more
source§fn redact_arg_values(
+ __cmd_name: &[&str],
+ __args: &[&str],
+) -> Result<Vec<String>, EarlyExit>
fn redact_arg_values( + __cmd_name: &[&str], + __args: &[&str], +) -> Result<Vec<String>, EarlyExit>
Get a String with just the argument names, e.g., options, flags, subcommands, etc, but
+without the values of the options and arguments. This can be useful as a means to capture
+anonymous usage statistics without revealing the content entered by the end user. Read more
source§impl PartialEq for RunArgs
impl PartialEq for RunArgs
impl StructuralPartialEq for RunArgs
Auto Trait Implementations§
impl Freeze for RunArgs
impl RefUnwindSafe for RunArgs
impl Send for RunArgs
impl Sync for RunArgs
impl Unpin for RunArgs
impl UnwindSafe for RunArgs
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
§impl<T> SubCommands for Twhere
+ T: SubCommand,
impl<T> SubCommands for Twhere
+ T: SubCommand,
§fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
Get a list of commands that are discovered at runtime.
Struct rustlings::VerifyArgs
source · pub(crate) struct VerifyArgs {}Expand description
Verifies all exercises according to the recommended order
+Trait Implementations§
source§impl Debug for VerifyArgs
impl Debug for VerifyArgs
source§impl FromArgs for VerifyArgs
impl FromArgs for VerifyArgs
source§fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
Construct the type from an input set of arguments. Read more
source§fn redact_arg_values(
+ __cmd_name: &[&str],
+ __args: &[&str],
+) -> Result<Vec<String>, EarlyExit>
fn redact_arg_values( + __cmd_name: &[&str], + __args: &[&str], +) -> Result<Vec<String>, EarlyExit>
Get a String with just the argument names, e.g., options, flags, subcommands, etc, but
+without the values of the options and arguments. This can be useful as a means to capture
+anonymous usage statistics without revealing the content entered by the end user. Read more
source§impl PartialEq for VerifyArgs
impl PartialEq for VerifyArgs
source§fn eq(&self, other: &VerifyArgs) -> bool
fn eq(&self, other: &VerifyArgs) -> bool
This method tests for
self and other values to be equal, and is used
+by ==.source§impl SubCommand for VerifyArgs
impl SubCommand for VerifyArgs
impl StructuralPartialEq for VerifyArgs
Auto Trait Implementations§
impl Freeze for VerifyArgs
impl RefUnwindSafe for VerifyArgs
impl Send for VerifyArgs
impl Sync for VerifyArgs
impl Unpin for VerifyArgs
impl UnwindSafe for VerifyArgs
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
§impl<T> SubCommands for Twhere
+ T: SubCommand,
impl<T> SubCommands for Twhere
+ T: SubCommand,
§fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
Get a list of commands that are discovered at runtime.
pub(crate) struct WatchArgs {}Expand description
Reruns verify when files were edited
Trait Implementations§
source§impl FromArgs for WatchArgs
impl FromArgs for WatchArgs
source§fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>
Construct the type from an input set of arguments. Read more
source§fn redact_arg_values(
+ __cmd_name: &[&str],
+ __args: &[&str],
+) -> Result<Vec<String>, EarlyExit>
fn redact_arg_values( + __cmd_name: &[&str], + __args: &[&str], +) -> Result<Vec<String>, EarlyExit>
Get a String with just the argument names, e.g., options, flags, subcommands, etc, but
+without the values of the options and arguments. This can be useful as a means to capture
+anonymous usage statistics without revealing the content entered by the end user. Read more
source§impl PartialEq for WatchArgs
impl PartialEq for WatchArgs
impl StructuralPartialEq for WatchArgs
Auto Trait Implementations§
impl Freeze for WatchArgs
impl RefUnwindSafe for WatchArgs
impl Send for WatchArgs
impl Sync for WatchArgs
impl Unpin for WatchArgs
impl UnwindSafe for WatchArgs
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
§impl<T> SubCommands for Twhere
+ T: SubCommand,
impl<T> SubCommands for Twhere
+ T: SubCommand,
§fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
fn dynamic_commands() -> &'static [&'static CommandInfo<'static>]
Get a list of commands that are discovered at runtime.
Redirecting to macro.success.html...
+ + + \ No newline at end of file diff --git a/doc/rustlings/ui/macro.success.html b/doc/rustlings/ui/macro.success.html new file mode 100644 index 00000000..4fa7136e --- /dev/null +++ b/doc/rustlings/ui/macro.success.html @@ -0,0 +1,3 @@ +Redirecting to macro.warn.html...
+ + + \ No newline at end of file diff --git a/doc/rustlings/ui/macro.warn.html b/doc/rustlings/ui/macro.warn.html new file mode 100644 index 00000000..8078ed79 --- /dev/null +++ b/doc/rustlings/ui/macro.warn.html @@ -0,0 +1,3 @@ +enum RunMode {
+ Interactive,
+ NonInteractive,
+}Variants§
Auto Trait Implementations§
impl Freeze for RunMode
impl RefUnwindSafe for RunMode
impl Send for RunMode
impl Sync for RunMode
impl Unpin for RunMode
impl UnwindSafe for RunMode
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
impl<T> BorrowMut<T> for Twhere
+ T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
U::from(self).")
\ No newline at end of file
diff --git a/doc/search.desc/hello_world/hello_world-desc-0-.js b/doc/search.desc/hello_world/hello_world-desc-0-.js
new file mode 100644
index 00000000..a13d6ed4
--- /dev/null
+++ b/doc/search.desc/hello_world/hello_world-desc-0-.js
@@ -0,0 +1 @@
+searchState.loadedDescShard("hello_world", 0, "")
\ No newline at end of file
diff --git a/doc/search.desc/rustlings/rustlings-desc-0-.js b/doc/search.desc/rustlings/rustlings-desc-0-.js
new file mode 100644
index 00000000..e383ff3a
--- /dev/null
+++ b/doc/search.desc/rustlings/rustlings-desc-0-.js
@@ -0,0 +1 @@
+searchState.loadedDescShard("rustlings", 0, "Rustlings is a collection of small exercises to get you …\nReturns a hint for the given exercise\nLists the exercises available in Rustlings\nRuns/Tests a single exercise\nVerifies all exercises according to the recommended order\nReruns verify when files were edited\nprovide a string to match exercise names comma separated …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nthe name of the exercise\nthe name of the exercise\nshow only the names of the exercises\nshow outputs from the test exercises\nshow only the paths of the exercises\ndisplay only exercises that have been solved\ndisplay only exercises not yet solved\nshow the executable version\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nReturns the argument unchanged.\nCalls U::from(self).")
\ No newline at end of file
diff --git a/doc/settings.html b/doc/settings.html
new file mode 100644
index 00000000..bff663df
--- /dev/null
+++ b/doc/settings.html
@@ -0,0 +1 @@
+Rustdoc settings
Back1 +
pub mod list;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +
pub struct Stack<T> {
+ head: Link<T>,
+}
+
+type Link<T> = Option<Box<Node<T>>>;
+
+struct Node<T> {
+ elem: T,
+ next: Link<T>,
+}
+
+impl<T> Stack<T> {
+ pub fn new() -> Self {
+ Stack { head: None }
+ }
+
+ pub fn push(&mut self, elem: T) {
+ let new_node = Box::new(Node {
+ elem,
+ next: self.head.take(),
+ });
+
+ self.head = Some(new_node);
+ }
+
+ pub fn pop(&mut self) -> Option<T> {
+ self.head.take().map(|node| {
+ self.head = node.next;
+ node.elem
+ })
+ }
+
+ pub fn peek(&self) -> Option<&T> {
+ self.head.as_ref().map(|node| &node.elem)
+ }
+
+ pub fn peek_mut(&mut self) -> Option<&mut T> {
+ self.head.as_mut().map(|node| &mut node.elem)
+ }
+}
+
+impl<T> Default for Stack<T> {
+ fn default() -> Self {
+ Self::new()
+ }
+}
+
+impl<T> Drop for Stack<T> {
+ fn drop(&mut self) {
+ let mut cur_link = self.head.take();
+ while let Some(mut boxed_node) = cur_link {
+ cur_link = boxed_node.next.take();
+ }
+ }
+}
+
+pub struct IntoIter<T>(Stack<T>);
+
+impl<T> IntoIterator for Stack<T> {
+ type Item = T;
+ type IntoIter = IntoIter<T>;
+ fn into_iter(self) -> Self::IntoIter {
+ IntoIter(self)
+ }
+}
+
+impl<T> Iterator for IntoIter<T> {
+ type Item = T;
+ fn next(&mut self) -> Option<Self::Item> {
+ self.0.pop()
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::Stack;
+
+ #[test]
+ fn push_and_pop() {
+ let mut list = Stack::new();
+ assert_eq!(list.pop(), None);
+
+ list.push(1);
+ list.push(2);
+ list.push(3);
+ assert_eq!(list.pop(), Some(3));
+ assert_eq!(list.pop(), Some(2));
+
+ list.push(4);
+ list.push(5);
+ assert_eq!(list.pop(), Some(5));
+ assert_eq!(list.pop(), Some(4));
+ assert_eq!(list.pop(), Some(1));
+ assert_eq!(list.pop(), None);
+ }
+
+ #[test]
+ fn peek() {
+ let mut list = Stack::new();
+ assert_eq!(list.peek(), None);
+ assert_eq!(list.peek_mut(), None);
+
+ list.push(1);
+ list.push(2);
+ list.push(3);
+ assert_eq!(list.peek(), Some(&3));
+ assert_eq!(list.peek_mut(), Some(&mut 3));
+
+ if let Some(value) = list.peek_mut() {
+ *value = 42;
+ }
+ assert_eq!(list.peek(), Some(&42));
+ assert_eq!(list.pop(), Some(42));
+ }
+
+ #[test]
+ fn into_iter() {
+ let mut list = Stack::new();
+ list.push(1);
+ list.push(2);
+ list.push(3);
+
+ let mut iter = list.into_iter();
+ assert_eq!(iter.next(), Some(3));
+ assert_eq!(iter.next(), Some(2));
+ assert_eq!(iter.next(), Some(1));
+ assert_eq!(iter.next(), None);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +
use regex::Regex;
+use serde::Deserialize;
+use std::env;
+use std::fmt::{self, Display, Formatter};
+use std::fs::{self, remove_file, File};
+use std::io::Read;
+use std::path::PathBuf;
+use std::process::{self, Command};
+
+const RUSTC_COLOR_ARGS: &[&str] = &["--color", "always"];
+const I_AM_DONE_REGEX: &str = r"(?m)^\s*///?\s*I\s+AM\s+NOT\s+DONE";
+const CONTEXT: usize = 2;
+const CLIPPY_CARGO_TOML_PATH: &str = "./exercises/clippy/Cargo.toml";
+
+// Get a temporary file name that is hopefully unique
+#[inline]
+fn temp_file() -> String {
+ let thread_id: String = format!("{:?}", std::thread::current().id())
+ .chars()
+ .filter(|c| c.is_alphanumeric())
+ .collect();
+
+ format!("./temp_{}_{}", process::id(), thread_id)
+}
+
+// The mode of the exercise.
+#[derive(Deserialize, Copy, Clone, Debug)]
+#[serde(rename_all = "lowercase")]
+pub enum Mode {
+ // Indicates that the exercise should be compiled as a binary
+ Compile,
+ // Indicates that the exercise should be compiled as a test harness
+ Test,
+ // Indicates that the exercise should be linted with clippy
+ Clippy,
+}
+
+#[derive(Deserialize)]
+pub struct ExerciseList {
+ pub exercises: Vec<Exercise>,
+}
+
+// A representation of a rustlings exercise.
+// This is deserialized from the accompanying info.toml file
+#[derive(Deserialize, Debug)]
+pub struct Exercise {
+ // Name of the exercise
+ pub name: String,
+ // The path to the file containing the exercise's source code
+ pub path: PathBuf,
+ // The mode of the exercise (Test, Compile, or Clippy)
+ pub mode: Mode,
+ // The hint text associated with the exercise
+ pub hint: String,
+}
+
+// An enum to track of the state of an Exercise.
+// An Exercise can be either Done or Pending
+#[derive(PartialEq, Eq, Debug)]
+pub enum State {
+ // The state of the exercise once it's been completed
+ Done,
+ // The state of the exercise while it's not completed yet
+ Pending(Vec<ContextLine>),
+}
+
+// The context information of a pending exercise
+#[derive(PartialEq, Eq, Debug)]
+pub struct ContextLine {
+ // The source code that is still pending completion
+ pub line: String,
+ // The line number of the source code still pending completion
+ pub number: usize,
+ // Whether or not this is important
+ pub important: bool,
+}
+
+// The result of compiling an exercise
+pub struct CompiledExercise<'a> {
+ exercise: &'a Exercise,
+ _handle: FileHandle,
+}
+
+impl<'a> CompiledExercise<'a> {
+ // Run the compiled exercise
+ pub fn run(&self) -> Result<ExerciseOutput, ExerciseOutput> {
+ self.exercise.run()
+ }
+}
+
+// A representation of an already executed binary
+#[derive(Debug)]
+pub struct ExerciseOutput {
+ // The textual contents of the standard output of the binary
+ pub stdout: String,
+ // The textual contents of the standard error of the binary
+ pub stderr: String,
+}
+
+struct FileHandle;
+
+impl Drop for FileHandle {
+ fn drop(&mut self) {
+ clean();
+ }
+}
+
+impl Exercise {
+ pub fn compile(&self) -> Result<CompiledExercise, ExerciseOutput> {
+ let cmd = match self.mode {
+ Mode::Compile => Command::new("rustc")
+ .args([self.path.to_str().unwrap(), "-o", &temp_file()])
+ .args(RUSTC_COLOR_ARGS)
+ .output(),
+ Mode::Test => Command::new("rustc")
+ .args(["--test", self.path.to_str().unwrap(), "-o", &temp_file()])
+ .args(RUSTC_COLOR_ARGS)
+ .output(),
+ Mode::Clippy => {
+ let cargo_toml = format!(
+ r#"[package]
+name = "{}"
+version = "0.0.1"
+edition = "2018"
+[[bin]]
+name = "{}"
+path = "{}.rs""#,
+ self.name, self.name, self.name
+ );
+ let cargo_toml_error_msg = if env::var("NO_EMOJI").is_ok() {
+ "Failed to write Clippy Cargo.toml file."
+ } else {
+ "Failed to write 📎 Clippy 📎 Cargo.toml file."
+ };
+ fs::write(CLIPPY_CARGO_TOML_PATH, cargo_toml).expect(cargo_toml_error_msg);
+ // To support the ability to run the clippy exercises, build
+ // an executable, in addition to running clippy. With a
+ // compilation failure, this would silently fail. But we expect
+ // clippy to reflect the same failure while compiling later.
+ Command::new("rustc")
+ .args([self.path.to_str().unwrap(), "-o", &temp_file()])
+ .args(RUSTC_COLOR_ARGS)
+ .output()
+ .expect("Failed to compile!");
+ // Due to an issue with Clippy, a cargo clean is required to catch all lints.
+ // See https://github.com/rust-lang/rust-clippy/issues/2604
+ // This is already fixed on Clippy's master branch. See this issue to track merging into Cargo:
+ // https://github.com/rust-lang/rust-clippy/issues/3837
+ Command::new("cargo")
+ .args(["clean", "--manifest-path", CLIPPY_CARGO_TOML_PATH])
+ .args(RUSTC_COLOR_ARGS)
+ .output()
+ .expect("Failed to run 'cargo clean'");
+ Command::new("cargo")
+ .args(["clippy", "--manifest-path", CLIPPY_CARGO_TOML_PATH])
+ .args(RUSTC_COLOR_ARGS)
+ .args(["--", "-D", "warnings", "-D", "clippy::float_cmp"])
+ .output()
+ }
+ }
+ .expect("Failed to run 'compile' command.");
+
+ if cmd.status.success() {
+ Ok(CompiledExercise {
+ exercise: self,
+ _handle: FileHandle,
+ })
+ } else {
+ clean();
+ Err(ExerciseOutput {
+ stdout: String::from_utf8_lossy(&cmd.stdout).to_string(),
+ stderr: String::from_utf8_lossy(&cmd.stderr).to_string(),
+ })
+ }
+ }
+
+ fn run(&self) -> Result<ExerciseOutput, ExerciseOutput> {
+ let arg = match self.mode {
+ Mode::Test => "--show-output",
+ _ => "",
+ };
+ let cmd = Command::new(temp_file())
+ .arg(arg)
+ .output()
+ .expect("Failed to run 'run' command");
+
+ let output = ExerciseOutput {
+ stdout: String::from_utf8_lossy(&cmd.stdout).to_string(),
+ stderr: String::from_utf8_lossy(&cmd.stderr).to_string(),
+ };
+
+ if cmd.status.success() {
+ Ok(output)
+ } else {
+ Err(output)
+ }
+ }
+
+ pub fn state(&self) -> State {
+ let mut source_file =
+ File::open(&self.path).expect("We were unable to open the exercise file!");
+
+ let source = {
+ let mut s = String::new();
+ source_file
+ .read_to_string(&mut s)
+ .expect("We were unable to read the exercise file!");
+ s
+ };
+
+ let re = Regex::new(I_AM_DONE_REGEX).unwrap();
+
+ if !re.is_match(&source) {
+ return State::Done;
+ }
+
+ let matched_line_index = source
+ .lines()
+ .enumerate()
+ .find_map(|(i, line)| if re.is_match(line) { Some(i) } else { None })
+ .expect("This should not happen at all");
+
+ let min_line = ((matched_line_index as i32) - (CONTEXT as i32)).max(0) as usize;
+ let max_line = matched_line_index + CONTEXT;
+
+ let context = source
+ .lines()
+ .enumerate()
+ .filter(|&(i, _)| i >= min_line && i <= max_line)
+ .map(|(i, line)| ContextLine {
+ line: line.to_string(),
+ number: i + 1,
+ important: i == matched_line_index,
+ })
+ .collect();
+
+ State::Pending(context)
+ }
+
+ // Check that the exercise looks to be solved using self.state()
+ // This is not the best way to check since
+ // the user can just remove the "I AM NOT DONE" string from the file
+ // without actually having solved anything.
+ // The only other way to truly check this would to compile and run
+ // the exercise; which would be both costly and counterintuitive
+ pub fn looks_done(&self) -> bool {
+ self.state() == State::Done
+ }
+}
+
+impl Display for Exercise {
+ fn fmt(&self, f: &mut Formatter) -> fmt::Result {
+ write!(f, "{}", self.path.to_str().unwrap())
+ }
+}
+
+#[inline]
+fn clean() {
+ let _ignored = remove_file(temp_file());
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+ use std::path::Path;
+
+ #[test]
+ fn test_clean() {
+ File::create(temp_file()).unwrap();
+ let exercise = Exercise {
+ name: String::from("example"),
+ path: PathBuf::from("tests/fixture/state/pending_exercise.rs"),
+ mode: Mode::Compile,
+ hint: String::from(""),
+ };
+ let compiled = exercise.compile().unwrap();
+ drop(compiled);
+ assert!(!Path::new(&temp_file()).exists());
+ }
+
+ #[test]
+ fn test_pending_state() {
+ let exercise = Exercise {
+ name: "pending_exercise".into(),
+ path: PathBuf::from("tests/fixture/state/pending_exercise.rs"),
+ mode: Mode::Compile,
+ hint: String::new(),
+ };
+
+ let state = exercise.state();
+ let expected = vec![
+ ContextLine {
+ line: "// fake_exercise".to_string(),
+ number: 1,
+ important: false,
+ },
+ ContextLine {
+ line: "".to_string(),
+ number: 2,
+ important: false,
+ },
+ ContextLine {
+ line: "// I AM NOT DONE".to_string(),
+ number: 3,
+ important: true,
+ },
+ ContextLine {
+ line: "".to_string(),
+ number: 4,
+ important: false,
+ },
+ ContextLine {
+ line: "fn main() {".to_string(),
+ number: 5,
+ important: false,
+ },
+ ];
+
+ assert_eq!(state, State::Pending(expected));
+ }
+
+ #[test]
+ fn test_finished_exercise() {
+ let exercise = Exercise {
+ name: "finished_exercise".into(),
+ path: PathBuf::from("tests/fixture/state/finished_exercise.rs"),
+ mode: Mode::Compile,
+ hint: String::new(),
+ };
+
+ assert_eq!(exercise.state(), State::Done);
+ }
+
+ #[test]
+ fn test_exercise_with_output() {
+ let exercise = Exercise {
+ name: "exercise_with_output".into(),
+ path: PathBuf::from("tests/fixture/success/testSuccess.rs"),
+ mode: Mode::Test,
+ hint: String::new(),
+ };
+ let out = exercise.compile().unwrap().run().unwrap();
+ assert!(out.stdout.contains("THIS TEST TOO SHALL PASS"));
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +
use crate::exercise::{Exercise, ExerciseList};
+use crate::run::run;
+use crate::verify::verify;
+use argh::FromArgs;
+use console::Emoji;
+use notify::DebouncedEvent;
+use notify::{RecommendedWatcher, RecursiveMode, Watcher};
+use std::ffi::OsStr;
+use std::fs;
+use std::io::{self, prelude::*};
+use std::path::Path;
+use std::process::{Command, Stdio};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::mpsc::{channel, RecvTimeoutError};
+use std::sync::{Arc, Mutex};
+use std::thread;
+use std::time::Duration;
+
+#[macro_use]
+mod ui;
+
+mod exercise;
+mod run;
+mod verify;
+
+// In sync with crate version
+const VERSION: &str = "4.6.0";
+
+#[derive(FromArgs, PartialEq, Debug)]
+/// Rustlings is a collection of small exercises to get you used to writing and reading Rust code
+struct Args {
+ /// show outputs from the test exercises
+ #[argh(switch)]
+ nocapture: bool,
+ /// show the executable version
+ #[argh(switch, short = 'v')]
+ version: bool,
+ #[argh(subcommand)]
+ nested: Option<Subcommands>,
+}
+
+#[derive(FromArgs, PartialEq, Debug)]
+#[argh(subcommand)]
+enum Subcommands {
+ Verify(VerifyArgs),
+ Watch(WatchArgs),
+ Run(RunArgs),
+ Hint(HintArgs),
+ List(ListArgs),
+}
+
+#[derive(FromArgs, PartialEq, Debug)]
+#[argh(subcommand, name = "verify")]
+/// Verifies all exercises according to the recommended order
+struct VerifyArgs {}
+
+#[derive(FromArgs, PartialEq, Debug)]
+#[argh(subcommand, name = "watch")]
+/// Reruns `verify` when files were edited
+struct WatchArgs {}
+
+#[derive(FromArgs, PartialEq, Debug)]
+#[argh(subcommand, name = "run")]
+/// Runs/Tests a single exercise
+struct RunArgs {
+ #[argh(positional)]
+ /// the name of the exercise
+ name: String,
+}
+
+#[derive(FromArgs, PartialEq, Debug)]
+#[argh(subcommand, name = "hint")]
+/// Returns a hint for the given exercise
+struct HintArgs {
+ #[argh(positional)]
+ /// the name of the exercise
+ name: String,
+}
+
+#[derive(FromArgs, PartialEq, Debug)]
+#[argh(subcommand, name = "list")]
+/// Lists the exercises available in Rustlings
+struct ListArgs {
+ #[argh(switch, short = 'p')]
+ /// show only the paths of the exercises
+ paths: bool,
+ #[argh(switch, short = 'n')]
+ /// show only the names of the exercises
+ names: bool,
+ #[argh(option, short = 'f')]
+ /// provide a string to match exercise names
+ /// comma separated patterns are acceptable
+ filter: Option<String>,
+ #[argh(switch, short = 'u')]
+ /// display only exercises not yet solved
+ unsolved: bool,
+ #[argh(switch, short = 's')]
+ /// display only exercises that have been solved
+ solved: bool,
+}
+
+fn main() {
+ let args: Args = argh::from_env();
+
+ if args.version {
+ println!("v{VERSION}");
+ std::process::exit(0);
+ }
+
+ if args.nested.is_none() {
+ println!();
+ println!(r#" welcome to... "#);
+ println!(r#" _ _ _ "#);
+ println!(r#" _ __ _ _ ___| |_| (_)_ __ __ _ ___ "#);
+ println!(r#" | '__| | | / __| __| | | '_ \ / _` / __| "#);
+ println!(r#" | | | |_| \__ \ |_| | | | | | (_| \__ \ "#);
+ println!(r#" |_| \__,_|___/\__|_|_|_| |_|\__, |___/ "#);
+ println!(r#" |___/ "#);
+ println!();
+ }
+
+ if !Path::new("info.toml").exists() {
+ println!(
+ "{} must be run from the rustlings directory",
+ std::env::current_exe().unwrap().to_str().unwrap()
+ );
+ println!("Try `cd rustlings/`!");
+ std::process::exit(1);
+ }
+
+ if !rustc_exists() {
+ println!("We cannot find `rustc`.");
+ println!("Try running `rustc --version` to diagnose your problem.");
+ println!("For instructions on how to install Rust, check the README.");
+ std::process::exit(1);
+ }
+
+ let toml_str = &fs::read_to_string("info.toml").unwrap();
+ let exercises = toml::from_str::<ExerciseList>(toml_str).unwrap().exercises;
+ let verbose = args.nocapture;
+
+ let command = args.nested.unwrap_or_else(|| {
+ let text = "Thanks for installing Rustlings!
+
+Is this your first time? Don't worry, Rustlings was made for beginners! We are
+going to teach you a lot of things about Rust, but before we can get
+started, here's a couple of notes about how Rustlings operates:
+
+1. The central concept behind Rustlings is that you solve exercises. These
+ exercises usually have some sort of syntax error in them, which will cause
+ them to fail compilation or testing. Sometimes there's a logic error instead
+ of a syntax error. No matter what error, it's your job to find it and fix it!
+ You'll know when you fixed it because then, the exercise will compile and
+ Rustlings will be able to move on to the next exercise.
+2. If you run Rustlings in watch mode (which we recommend), it'll automatically
+ start with the first exercise. Don't get confused by an error message popping
+ up as soon as you run Rustlings! This is part of the exercise that you're
+ supposed to solve, so open the exercise file in an editor and start your
+ detective work!
+3. If you're stuck on an exercise, there is a helpful hint you can view by typing
+ 'hint' (in watch mode), or running `rustlings hint myexercise`.
+4. If an exercise doesn't make sense to you, feel free to open an issue on GitHub!
+ (https://github.com/rust-lang/rustlings/issues/new). We look at every issue,
+ and sometimes, other learners do too so you can help each other out!
+
+Got all that? Great! To get started, run `rustlings watch` in order to get the first
+exercise. Make sure to have your editor open!
+";
+ println!("{text}");
+ std::process::exit(0);
+ });
+ match command {
+ Subcommands::List(subargs) => {
+ if !subargs.paths && !subargs.names {
+ println!("{:<17}\t{:<46}\t{:<7}", "Name", "Path", "Status");
+ }
+ let mut exercises_done: u16 = 0;
+ let filters = subargs.filter.clone().unwrap_or_default().to_lowercase();
+ exercises.iter().for_each(|e| {
+ let fname = format!("{}", e.path.display());
+ let filter_cond = filters
+ .split(',')
+ .filter(|f| !f.trim().is_empty())
+ .any(|f| e.name.contains(f) || fname.contains(f));
+ let status = if e.looks_done() {
+ exercises_done += 1;
+ "Done"
+ } else {
+ "Pending"
+ };
+ let solve_cond = {
+ (e.looks_done() && subargs.solved)
+ || (!e.looks_done() && subargs.unsolved)
+ || (!subargs.solved && !subargs.unsolved)
+ };
+ if solve_cond && (filter_cond || subargs.filter.is_none()) {
+ let line = if subargs.paths {
+ format!("{fname}\n")
+ } else if subargs.names {
+ format!("{}\n", e.name)
+ } else {
+ format!("{:<17}\t{:<46}\t{:<7}\n", e.name, fname, status)
+ };
+ // Somehow using println! leads to the binary panicking
+ // when its output is piped.
+ // So, we're handling a Broken Pipe error and exiting with 0 anyway
+ let stdout = std::io::stdout();
+ {
+ let mut handle = stdout.lock();
+ handle.write_all(line.as_bytes()).unwrap_or_else(|e| {
+ match e.kind() {
+ std::io::ErrorKind::BrokenPipe => std::process::exit(0),
+ _ => std::process::exit(1),
+ };
+ });
+ }
+ }
+ });
+ let percentage_progress = exercises_done as f32 / exercises.len() as f32 * 100.0;
+ println!(
+ "Progress: You completed {} / {} exercises ({:.2} %).",
+ exercises_done,
+ exercises.len(),
+ percentage_progress
+ );
+ std::process::exit(0);
+ }
+
+ Subcommands::Run(subargs) => {
+ let exercise = find_exercise(&subargs.name, &exercises);
+
+ run(exercise, verbose).unwrap_or_else(|_| std::process::exit(1));
+ }
+
+ Subcommands::Hint(subargs) => {
+ let exercise = find_exercise(&subargs.name, &exercises);
+
+ println!("{}", exercise.hint);
+ }
+
+ Subcommands::Verify(_subargs) => {
+ verify(&exercises, verbose).unwrap_or_else(|_| std::process::exit(1));
+ }
+
+ Subcommands::Watch(_subargs) => match watch(&exercises, verbose) {
+ Err(e) => {
+ println!("Error: Could not watch your progress. Error message was {e:?}.");
+ println!("Most likely you've run out of disk space or your 'inotify limit' has been reached.");
+ std::process::exit(1);
+ }
+ Ok(WatchStatus::Finished) => {
+ println!(
+ "{emoji} All exercises completed! {emoji}",
+ emoji = Emoji("🎉", "★")
+ );
+ println!();
+ println!("+----------------------------------------------------+");
+ println!("| You made it to the Fe-nish line! |");
+ println!("+-------------------------- ------------------------+");
+ println!(" \\/ ");
+ println!(" ▒▒ ▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒ ▒▒ ");
+ println!(" ▒▒▒▒ ▒▒ ▒▒ ▒▒ ▒▒ ▒▒ ▒▒ ▒▒▒▒ ");
+ println!(" ▒▒▒▒ ▒▒ ▒▒ ▒▒ ▒▒ ▒▒ ▒▒▒▒ ");
+ println!(" ░░▒▒▒▒░░▒▒ ▒▒ ▒▒ ▒▒ ▒▒░░▒▒▒▒ ");
+ println!(" ▓▓▓▓▓▓▓▓ ▓▓ ▓▓██ ▓▓ ▓▓██ ▓▓ ▓▓▓▓▓▓▓▓ ");
+ println!(" ▒▒▒▒ ▒▒ ████ ▒▒ ████ ▒▒░░ ▒▒▒▒ ");
+ println!(" ▒▒ ▒▒▒▒▒▒ ▒▒▒▒▒▒ ▒▒▒▒▒▒ ▒▒ ");
+ println!(" ▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▒▒▒▒▒▒▒▒▓▓▒▒▓▓▒▒▒▒▒▒▒▒ ");
+ println!(" ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ");
+ println!(" ▒▒▒▒▒▒▒▒▒▒██▒▒▒▒▒▒██▒▒▒▒▒▒▒▒▒▒ ");
+ println!(" ▒▒ ▒▒▒▒▒▒▒▒▒▒██████▒▒▒▒▒▒▒▒▒▒ ▒▒ ");
+ println!(" ▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒ ");
+ println!(" ▒▒ ▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒ ▒▒ ");
+ println!(" ▒▒ ▒▒ ▒▒ ▒▒ ▒▒ ▒▒ ");
+ println!(" ▒▒ ▒▒ ▒▒ ▒▒ ");
+ println!();
+ println!("We hope you enjoyed learning about the various aspects of Rust!");
+ println!(
+ "If you noticed any issues, please don't hesitate to report them to our repo."
+ );
+ println!(
+ "You can also contribute your own exercises to help the greater community!"
+ );
+ println!();
+ println!("Before reporting an issue or contributing, please read our guidelines:");
+ println!("https://github.com/rust-lang/rustlings/blob/main/CONTRIBUTING.md");
+ }
+ Ok(WatchStatus::Unfinished) => {
+ println!("We hope you're enjoying learning about Rust!");
+ println!("If you want to continue working on the exercises at a later point, you can simply run `rustlings watch` again");
+ }
+ },
+ }
+}
+
+fn spawn_watch_shell(
+ failed_exercise_hint: &Arc<Mutex<Option<String>>>,
+ should_quit: Arc<AtomicBool>,
+) {
+ let failed_exercise_hint = Arc::clone(failed_exercise_hint);
+ println!("Welcome to watch mode! You can type 'help' to get an overview of the commands you can use here.");
+ thread::spawn(move || loop {
+ let mut input = String::new();
+ match io::stdin().read_line(&mut input) {
+ Ok(_) => {
+ let input = input.trim();
+ if input == "hint" {
+ if let Some(hint) = &*failed_exercise_hint.lock().unwrap() {
+ println!("{hint}");
+ }
+ } else if input == "clear" {
+ println!("\x1B[2J\x1B[1;1H");
+ } else if input.eq("quit") {
+ should_quit.store(true, Ordering::SeqCst);
+ println!("Bye!");
+ } else if input.eq("help") {
+ println!("Commands available to you in watch mode:");
+ println!(" hint - prints the current exercise's hint");
+ println!(" clear - clears the screen");
+ println!(" quit - quits watch mode");
+ println!(" help - displays this help message");
+ println!();
+ println!("Watch mode automatically re-evaluates the current exercise");
+ println!("when you edit a file's contents.")
+ } else {
+ println!("unknown command: {input}");
+ }
+ }
+ Err(error) => println!("error reading command: {error}"),
+ }
+ });
+}
+
+fn find_exercise<'a>(name: &str, exercises: &'a [Exercise]) -> &'a Exercise {
+ if name.eq("next") {
+ exercises
+ .iter()
+ .find(|e| !e.looks_done())
+ .unwrap_or_else(|| {
+ println!("🎉 Congratulations! You have done all the exercises!");
+ println!("🔚 There are no more exercises to do next!");
+ std::process::exit(1)
+ })
+ } else {
+ exercises
+ .iter()
+ .find(|e| e.name == name)
+ .unwrap_or_else(|| {
+ println!("No exercise found for '{name}'!");
+ std::process::exit(1)
+ })
+ }
+}
+
+enum WatchStatus {
+ Finished,
+ Unfinished,
+}
+
+fn watch(exercises: &[Exercise], verbose: bool) -> notify::Result<WatchStatus> {
+ /* Clears the terminal with an ANSI escape code.
+ Works in UNIX and newer Windows terminals. */
+ fn clear_screen() {
+ println!("\x1Bc");
+ }
+
+ let (tx, rx) = channel();
+ let should_quit = Arc::new(AtomicBool::new(false));
+
+ let mut watcher: RecommendedWatcher = Watcher::new(tx, Duration::from_secs(2))?;
+ watcher.watch(Path::new("./exercises"), RecursiveMode::Recursive)?;
+
+ clear_screen();
+
+ let to_owned_hint = |t: &Exercise| t.hint.to_owned();
+ let failed_exercise_hint = match verify(exercises.iter(), verbose) {
+ Ok(_) => return Ok(WatchStatus::Finished),
+ Err(exercise) => Arc::new(Mutex::new(Some(to_owned_hint(exercise)))),
+ };
+ spawn_watch_shell(&failed_exercise_hint, Arc::clone(&should_quit));
+ loop {
+ match rx.recv_timeout(Duration::from_secs(1)) {
+ Ok(event) => match event {
+ DebouncedEvent::Create(b) | DebouncedEvent::Chmod(b) | DebouncedEvent::Write(b) => {
+ if b.extension() == Some(OsStr::new("rs")) && b.exists() {
+ let filepath = b.as_path().canonicalize().unwrap();
+ let pending_exercises = exercises
+ .iter()
+ .skip_while(|e| !filepath.ends_with(&e.path))
+ // .filter(|e| filepath.ends_with(&e.path))
+ .chain(
+ exercises
+ .iter()
+ .filter(|e| !e.looks_done() && !filepath.ends_with(&e.path)),
+ );
+ clear_screen();
+ match verify(pending_exercises, verbose) {
+ Ok(_) => return Ok(WatchStatus::Finished),
+ Err(exercise) => {
+ let mut failed_exercise_hint = failed_exercise_hint.lock().unwrap();
+ *failed_exercise_hint = Some(to_owned_hint(exercise));
+ }
+ }
+ }
+ }
+ _ => {}
+ },
+ Err(RecvTimeoutError::Timeout) => {
+ // the timeout expired, just check the `should_quit` variable below then loop again
+ }
+ Err(e) => println!("watch error: {e:?}"),
+ }
+ // Check if we need to exit
+ if should_quit.load(Ordering::SeqCst) {
+ return Ok(WatchStatus::Unfinished);
+ }
+ }
+}
+
+fn rustc_exists() -> bool {
+ Command::new("rustc")
+ .args(["--version"])
+ .stdout(Stdio::null())
+ .spawn()
+ .and_then(|mut child| child.wait())
+ .map(|status| status.success())
+ .unwrap_or(false)
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +
use crate::exercise::{Exercise, Mode};
+use crate::verify::test;
+use indicatif::ProgressBar;
+use std::time::Duration;
+
+// Invoke the rust compiler on the path of the given exercise,
+// and run the ensuing binary.
+// The verbose argument helps determine whether or not to show
+// the output from the test harnesses (if the mode of the exercise is test)
+pub fn run(exercise: &Exercise, verbose: bool) -> Result<(), ()> {
+ match exercise.mode {
+ Mode::Test => test(exercise, verbose)?,
+ Mode::Compile => compile_and_run(exercise)?,
+ Mode::Clippy => compile_and_run(exercise)?,
+ }
+ Ok(())
+}
+
+// Invoke the rust compiler on the path of the given exercise
+// and run the ensuing binary.
+// This is strictly for non-test binaries, so output is displayed
+fn compile_and_run(exercise: &Exercise) -> Result<(), ()> {
+ let progress_bar = ProgressBar::new_spinner();
+ progress_bar.set_message(format!("Compiling {exercise}..."));
+ progress_bar.enable_steady_tick(Duration::from_millis(100));
+
+ let compilation_result = exercise.compile();
+ let compilation = match compilation_result {
+ Ok(compilation) => compilation,
+ Err(output) => {
+ progress_bar.finish_and_clear();
+ warn!(
+ "Compilation of {} failed!, Compiler error message:\n",
+ exercise
+ );
+ println!("{}", output.stderr);
+ return Err(());
+ }
+ };
+
+ progress_bar.set_message(format!("Running {exercise}..."));
+ let result = compilation.run();
+ progress_bar.finish_and_clear();
+
+ match result {
+ Ok(output) => {
+ println!("{}", output.stdout);
+ success!("Successfully ran {}", exercise);
+ Ok(())
+ }
+ Err(output) => {
+ println!("{}", output.stdout);
+ println!("{}", output.stderr);
+
+ warn!("Ran {} with errors", exercise);
+ Err(())
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +
macro_rules! warn {
+ ($fmt:literal, $ex:expr) => {{
+ use console::{style, Emoji};
+ use std::env;
+ let formatstr = format!($fmt, $ex);
+ if env::var("NO_EMOJI").is_ok() {
+ println!("{} {}", style("!").red(), style(formatstr).red());
+ } else {
+ println!(
+ "{} {}",
+ style(Emoji("⚠️ ", "!")).red(),
+ style(formatstr).red()
+ );
+ }
+ }};
+}
+
+macro_rules! success {
+ ($fmt:literal, $ex:expr) => {{
+ use console::{style, Emoji};
+ use std::env;
+ let formatstr = format!($fmt, $ex);
+ if env::var("NO_EMOJI").is_ok() {
+ println!("{} {}", style("✓").green(), style(formatstr).green());
+ } else {
+ println!(
+ "{} {}",
+ style(Emoji("✅", "✓")).green(),
+ style(formatstr).green()
+ );
+ }
+ }};
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +
use crate::exercise::{CompiledExercise, Exercise, Mode, State};
+use console::style;
+use indicatif::ProgressBar;
+use std::env;
+use std::time::Duration;
+
+// Verify that the provided container of Exercise objects
+// can be compiled and run without any failures.
+// Any such failures will be reported to the end user.
+// If the Exercise being verified is a test, the verbose boolean
+// determines whether or not the test harness outputs are displayed.
+pub fn verify<'a>(
+ start_at: impl IntoIterator<Item = &'a Exercise>,
+ verbose: bool,
+) -> Result<(), &'a Exercise> {
+ for exercise in start_at {
+ let compile_result = match exercise.mode {
+ Mode::Test => compile_and_test(exercise, RunMode::Interactive, verbose),
+ Mode::Compile => compile_and_run_interactively(exercise),
+ Mode::Clippy => compile_only(exercise),
+ };
+ if !compile_result.unwrap_or(false) {
+ return Err(exercise);
+ }
+ }
+ Ok(())
+}
+
+enum RunMode {
+ Interactive,
+ NonInteractive,
+}
+
+// Compile and run the resulting test harness of the given Exercise
+pub fn test(exercise: &Exercise, verbose: bool) -> Result<(), ()> {
+ compile_and_test(exercise, RunMode::NonInteractive, verbose)?;
+ Ok(())
+}
+
+// Invoke the rust compiler without running the resulting binary
+fn compile_only(exercise: &Exercise) -> Result<bool, ()> {
+ let progress_bar = ProgressBar::new_spinner();
+ progress_bar.set_message(format!("Compiling {exercise}..."));
+ progress_bar.enable_steady_tick(Duration::from_millis(100));
+
+ let _ = compile(exercise, &progress_bar)?;
+ progress_bar.finish_and_clear();
+
+ success!("Successfully compiled {}!", exercise);
+ Ok(prompt_for_completion(exercise, None))
+}
+
+// Compile the given Exercise and run the resulting binary in an interactive mode
+fn compile_and_run_interactively(exercise: &Exercise) -> Result<bool, ()> {
+ let progress_bar = ProgressBar::new_spinner();
+ progress_bar.set_message(format!("Compiling {exercise}..."));
+ progress_bar.enable_steady_tick(Duration::from_millis(100));
+
+ let compilation = compile(exercise, &progress_bar)?;
+
+ progress_bar.set_message(format!("Running {exercise}..."));
+ let result = compilation.run();
+ progress_bar.finish_and_clear();
+
+ let output = match result {
+ Ok(output) => output,
+ Err(output) => {
+ warn!("Ran {} with errors", exercise);
+ println!("{}", output.stdout);
+ println!("{}", output.stderr);
+ return Err(());
+ }
+ };
+
+ success!("Successfully ran {}!", exercise);
+
+ Ok(prompt_for_completion(exercise, Some(output.stdout)))
+}
+
+// Compile the given Exercise as a test harness and display
+// the output if verbose is set to true
+fn compile_and_test(exercise: &Exercise, run_mode: RunMode, verbose: bool) -> Result<bool, ()> {
+ let progress_bar = ProgressBar::new_spinner();
+ progress_bar.set_message(format!("Testing {exercise}..."));
+ progress_bar.enable_steady_tick(Duration::from_millis(100));
+
+ let compilation = compile(exercise, &progress_bar)?;
+ let result = compilation.run();
+ progress_bar.finish_and_clear();
+
+ match result {
+ Ok(output) => {
+ if verbose {
+ println!("{}", output.stdout);
+ }
+ success!("Successfully tested {}", &exercise);
+ if let RunMode::Interactive = run_mode {
+ Ok(prompt_for_completion(exercise, None))
+ } else {
+ Ok(true)
+ }
+ }
+ Err(output) => {
+ warn!(
+ "Testing of {} failed! Please try again. Here's the output:",
+ exercise
+ );
+ println!("{}", output.stdout);
+ Err(())
+ }
+ }
+}
+
+// Compile the given Exercise and return an object with information
+// about the state of the compilation
+fn compile<'a>(
+ exercise: &'a Exercise,
+ progress_bar: &ProgressBar,
+) -> Result<CompiledExercise<'a>, ()> {
+ let compilation_result = exercise.compile();
+
+ match compilation_result {
+ Ok(compilation) => Ok(compilation),
+ Err(output) => {
+ progress_bar.finish_and_clear();
+ warn!(
+ "Compiling of {} failed! Please try again. Here's the output:",
+ exercise
+ );
+ println!("{}", output.stderr);
+ Err(())
+ }
+ }
+}
+
+fn prompt_for_completion(exercise: &Exercise, prompt_output: Option<String>) -> bool {
+ let context = match exercise.state() {
+ State::Done => return true,
+ State::Pending(context) => context,
+ };
+
+ let no_emoji = env::var("NO_EMOJI").is_ok();
+
+ let clippy_success_msg = if no_emoji {
+ "The code is compiling, and Clippy is happy!"
+ } else {
+ "The code is compiling, and 📎 Clippy 📎 is happy!"
+ };
+
+ let success_msg = match exercise.mode {
+ Mode::Compile => "The code is compiling!",
+ Mode::Test => "The code is compiling, and the tests pass!",
+ Mode::Clippy => clippy_success_msg,
+ };
+
+ println!();
+ if no_emoji {
+ println!("~*~ {success_msg} ~*~")
+ } else {
+ println!("🎉 🎉 {success_msg} 🎉 🎉")
+ }
+ println!();
+
+ if let Some(output) = prompt_output {
+ println!("Output:");
+ println!("{}", separator());
+ println!("{output}");
+ println!("{}", separator());
+ println!();
+ }
+
+ println!("You can keep working on this exercise,");
+ println!(
+ "or jump into the next one by removing the {} comment:",
+ style("`I AM NOT DONE`").bold()
+ );
+ println!();
+ for context_line in context {
+ let formatted_line = if context_line.important {
+ format!("{}", style(context_line.line).bold())
+ } else {
+ context_line.line.to_string()
+ };
+
+ println!(
+ "{:>2} {} {}",
+ style(context_line.number).blue().bold(),
+ style("|").blue(),
+ formatted_line
+ );
+ }
+
+ false
+}
+
+fn separator() -> console::StyledObject<&'static str> {
+ style("====================").bold()
+}
+"+searchState.loadingText+"
";searchState.showResults(search)},descShards:new Map(),loadDesc:async function({descShard,descIndex}){if(descShard.promise===null){descShard.promise=new Promise((resolve,reject)=>{descShard.resolve=resolve;const ds=descShard;const fname=`${ds.crate}-desc-${ds.shard}-`;const url=resourcePath(`search.desc/${descShard.crate}/${fname}`,".js",);loadScript(url,reject)})}const list=await descShard.promise;return list[descIndex]},loadedDescShard:function(crate,shard,data){this.descShards.get(crate)[shard].resolve(data.split("\n"))},};const toggleAllDocsId="toggle-all-docs";let savedHash="";function handleHashes(ev){if(ev!==null&&searchState.isDisplayed()&&ev.newURL){switchDisplayedElement(null);const hash=ev.newURL.slice(ev.newURL.indexOf("#")+1);if(browserSupportsHistoryApi()){history.replaceState(null,"",getNakedUrl()+window.location.search+"#"+hash)}const elem=document.getElementById(hash);if(elem){elem.scrollIntoView()}}const pageId=window.location.hash.replace(/^#/,"");if(savedHash!==pageId){savedHash=pageId;if(pageId!==""){expandSection(pageId)}}if(savedHash.startsWith("impl-")){const splitAt=savedHash.indexOf("/");if(splitAt!==-1){const implId=savedHash.slice(0,splitAt);const assocId=savedHash.slice(splitAt+1);const implElem=document.getElementById(implId);if(implElem&&implElem.parentElement.tagName==="SUMMARY"&&implElem.parentElement.parentElement.tagName==="DETAILS"){onEachLazy(implElem.parentElement.parentElement.querySelectorAll(`[id^="${assocId}"]`),item=>{const numbered=/([^-]+)-([0-9]+)/.exec(item.id);if(item.id===assocId||(numbered&&numbered[1]===assocId)){openParentDetails(item);item.scrollIntoView();setTimeout(()=>{window.location.replace("#"+item.id)},0)}},)}}}}function onHashChange(ev){hideSidebar();handleHashes(ev)}function openParentDetails(elem){while(elem){if(elem.tagName==="DETAILS"){elem.open=true}elem=elem.parentNode}}function expandSection(id){openParentDetails(document.getElementById(id))}function handleEscape(ev){searchState.clearInputTimeout();searchState.hideResults();ev.preventDefault();searchState.defocus();window.hideAllModals(true)}function handleShortcut(ev){const disableShortcuts=getSettingValue("disable-shortcuts")==="true";if(ev.ctrlKey||ev.altKey||ev.metaKey||disableShortcuts){return}if(document.activeElement.tagName==="INPUT"&&document.activeElement.type!=="checkbox"&&document.activeElement.type!=="radio"){switch(getVirtualKey(ev)){case"Escape":handleEscape(ev);break}}else{switch(getVirtualKey(ev)){case"Escape":handleEscape(ev);break;case"s":case"S":case"/":ev.preventDefault();searchState.focus();break;case"+":ev.preventDefault();expandAllDocs();break;case"-":ev.preventDefault();collapseAllDocs();break;case"?":showHelp();break;default:break}}}document.addEventListener("keypress",handleShortcut);document.addEventListener("keydown",handleShortcut);function addSidebarItems(){if(!window.SIDEBAR_ITEMS){return}const sidebar=document.getElementsByClassName("sidebar-elems")[0];function block(shortty,id,longty){const filtered=window.SIDEBAR_ITEMS[shortty];if(!filtered){return}const modpath=hasClass(document.querySelector(".rustdoc"),"mod")?"../":"";const h3=document.createElement("h3");h3.innerHTML=`${longty}`;const ul=document.createElement("ul");ul.className="block "+shortty;for(const name of filtered){let path;if(shortty==="mod"){path=`${modpath}${name}/index.html`}else{path=`${modpath}${shortty}.${name}.html`}let current_page=document.location.href.toString();if(current_page.endsWith("/")){current_page+="index.html"}const link=document.createElement("a");link.href=path;if(path===current_page){link.className="current"}link.textContent=name;const li=document.createElement("li");li.appendChild(link);ul.appendChild(li)}sidebar.appendChild(h3);sidebar.appendChild(ul)}if(sidebar){block("primitive","primitives","Primitive Types");block("mod","modules","Modules");block("macro","macros","Macros");block("struct","structs","Structs");block("enum","enums","Enums");block("constant","constants","Constants");block("static","static","Statics");block("trait","traits","Traits");block("fn","functions","Functions");block("type","types","Type Aliases");block("union","unions","Unions");block("foreigntype","foreign-types","Foreign Types");block("keyword","keywords","Keywords");block("opaque","opaque-types","Opaque Types");block("attr","attributes","Attribute Macros");block("derive","derives","Derive Macros");block("traitalias","trait-aliases","Trait Aliases")}}window.register_implementors=imp=>{const implementors=document.getElementById("implementors-list");const synthetic_implementors=document.getElementById("synthetic-implementors-list");const inlined_types=new Set();const TEXT_IDX=0;const SYNTHETIC_IDX=1;const TYPES_IDX=2;if(synthetic_implementors){onEachLazy(synthetic_implementors.getElementsByClassName("impl"),el=>{const aliases=el.getAttribute("data-aliases");if(!aliases){return}aliases.split(",").forEach(alias=>{inlined_types.add(alias)})})}let currentNbImpls=implementors.getElementsByClassName("impl").length;const traitName=document.querySelector(".main-heading h1 > .trait").textContent;const baseIdName="impl-"+traitName+"-";const libs=Object.getOwnPropertyNames(imp);const script=document.querySelector("script[data-ignore-extern-crates]");const ignoreExternCrates=new Set((script?script.getAttribute("data-ignore-extern-crates"):"").split(","),);for(const lib of libs){if(lib===window.currentCrate||ignoreExternCrates.has(lib)){continue}const structs=imp[lib];struct_loop:for(const struct of structs){const list=struct[SYNTHETIC_IDX]?synthetic_implementors:implementors;if(struct[SYNTHETIC_IDX]){for(const struct_type of struct[TYPES_IDX]){if(inlined_types.has(struct_type)){continue struct_loop}inlined_types.add(struct_type)}}const code=document.createElement("h3");code.innerHTML=struct[TEXT_IDX];addClass(code,"code-header");onEachLazy(code.getElementsByTagName("a"),elem=>{const href=elem.getAttribute("href");if(href&&!href.startsWith("#")&&!/^(?:[a-z+]+:)?\/\//.test(href)){elem.setAttribute("href",window.rootPath+href)}});const currentId=baseIdName+currentNbImpls;const anchor=document.createElement("a");anchor.href="#"+currentId;addClass(anchor,"anchor");const display=document.createElement("div");display.id=currentId;addClass(display,"impl");display.appendChild(anchor);display.appendChild(code);list.appendChild(display);currentNbImpls+=1}}};if(window.pending_implementors){window.register_implementors(window.pending_implementors)}window.register_type_impls=imp=>{if(!imp||!imp[window.currentCrate]){return}window.pending_type_impls=null;const idMap=new Map();let implementations=document.getElementById("implementations-list");let trait_implementations=document.getElementById("trait-implementations-list");let trait_implementations_header=document.getElementById("trait-implementations");const script=document.querySelector("script[data-self-path]");const selfPath=script?script.getAttribute("data-self-path"):null;const mainContent=document.querySelector("#main-content");const sidebarSection=document.querySelector(".sidebar section");let methods=document.querySelector(".sidebar .block.method");let associatedTypes=document.querySelector(".sidebar .block.associatedtype");let associatedConstants=document.querySelector(".sidebar .block.associatedconstant");let sidebarTraitList=document.querySelector(".sidebar .block.trait-implementation");for(const impList of imp[window.currentCrate]){const types=impList.slice(2);const text=impList[0];const isTrait=impList[1]!==0;const traitName=impList[1];if(types.indexOf(selfPath)===-1){continue}let outputList=isTrait?trait_implementations:implementations;if(outputList===null){const outputListName=isTrait?"Trait Implementations":"Implementations";const outputListId=isTrait?"trait-implementations-list":"implementations-list";const outputListHeaderId=isTrait?"trait-implementations":"implementations";const outputListHeader=document.createElement("h2");outputListHeader.id=outputListHeaderId;outputListHeader.innerText=outputListName;outputList=document.createElement("div");outputList.id=outputListId;if(isTrait){const link=document.createElement("a");link.href=`#${outputListHeaderId}`;link.innerText="Trait Implementations";const h=document.createElement("h3");h.appendChild(link);trait_implementations=outputList;trait_implementations_header=outputListHeader;sidebarSection.appendChild(h);sidebarTraitList=document.createElement("ul");sidebarTraitList.className="block trait-implementation";sidebarSection.appendChild(sidebarTraitList);mainContent.appendChild(outputListHeader);mainContent.appendChild(outputList)}else{implementations=outputList;if(trait_implementations){mainContent.insertBefore(outputListHeader,trait_implementations_header);mainContent.insertBefore(outputList,trait_implementations_header)}else{const mainContent=document.querySelector("#main-content");mainContent.appendChild(outputListHeader);mainContent.appendChild(outputList)}}}const template=document.createElement("template");template.innerHTML=text;onEachLazy(template.content.querySelectorAll("a"),elem=>{const href=elem.getAttribute("href");if(href&&!href.startsWith("#")&&!/^(?:[a-z+]+:)?\/\//.test(href)){elem.setAttribute("href",window.rootPath+href)}});onEachLazy(template.content.querySelectorAll("[id]"),el=>{let i=0;if(idMap.has(el.id)){i=idMap.get(el.id)}else if(document.getElementById(el.id)){i=1;while(document.getElementById(`${el.id}-${2 * i}`)){i=2*i}while(document.getElementById(`${el.id}-${i}`)){i+=1}}if(i!==0){const oldHref=`#${el.id}`;const newHref=`#${el.id}-${i}`;el.id=`${el.id}-${i}`;onEachLazy(template.content.querySelectorAll("a[href]"),link=>{if(link.getAttribute("href")===oldHref){link.href=newHref}})}idMap.set(el.id,i+1)});const templateAssocItems=template.content.querySelectorAll("section.tymethod, "+"section.method, section.associatedtype, section.associatedconstant");if(isTrait){const li=document.createElement("li");const a=document.createElement("a");a.href=`#${template.content.querySelector(".impl").id}`;a.textContent=traitName;li.appendChild(a);sidebarTraitList.append(li)}else{onEachLazy(templateAssocItems,item=>{let block=hasClass(item,"associatedtype")?associatedTypes:(hasClass(item,"associatedconstant")?associatedConstants:(methods));if(!block){const blockTitle=hasClass(item,"associatedtype")?"Associated Types":(hasClass(item,"associatedconstant")?"Associated Constants":("Methods"));const blockClass=hasClass(item,"associatedtype")?"associatedtype":(hasClass(item,"associatedconstant")?"associatedconstant":("method"));const blockHeader=document.createElement("h3");const blockLink=document.createElement("a");blockLink.href="#implementations";blockLink.innerText=blockTitle;blockHeader.appendChild(blockLink);block=document.createElement("ul");block.className=`block ${blockClass}`;const insertionReference=methods||sidebarTraitList;if(insertionReference){const insertionReferenceH=insertionReference.previousElementSibling;sidebarSection.insertBefore(blockHeader,insertionReferenceH);sidebarSection.insertBefore(block,insertionReferenceH)}else{sidebarSection.appendChild(blockHeader);sidebarSection.appendChild(block)}if(hasClass(item,"associatedtype")){associatedTypes=block}else if(hasClass(item,"associatedconstant")){associatedConstants=block}else{methods=block}}const li=document.createElement("li");const a=document.createElement("a");a.innerText=item.id.split("-")[0].split(".")[1];a.href=`#${item.id}`;li.appendChild(a);block.appendChild(li)})}outputList.appendChild(template.content)}for(const list of[methods,associatedTypes,associatedConstants,sidebarTraitList]){if(!list){continue}const newChildren=Array.prototype.slice.call(list.children);newChildren.sort((a,b)=>{const aI=a.innerText;const bI=b.innerText;return aI"+window.NOTABLE_TRAITS[notable_ty]+"
"}else{if(e.getAttribute("title")!==null){e.setAttribute("data-title",e.getAttribute("title"));e.removeAttribute("title")}if(e.getAttribute("data-title")!==null){const titleContent=document.createElement("div");titleContent.className="content";titleContent.appendChild(document.createTextNode(e.getAttribute("data-title")));wrapper.appendChild(titleContent)}}wrapper.className="tooltip popover";const focusCatcher=document.createElement("div");focusCatcher.setAttribute("tabindex","0");focusCatcher.onfocus=hideTooltip;wrapper.appendChild(focusCatcher);const pos=e.getBoundingClientRect();wrapper.style.top=(pos.top+window.scrollY+pos.height)+"px";wrapper.style.left=0;wrapper.style.right="auto";wrapper.style.visibility="hidden";const body=document.getElementsByTagName("body")[0];body.appendChild(wrapper);const wrapperPos=wrapper.getBoundingClientRect();const finalPos=pos.left+window.scrollX-wrapperPos.width+24;if(finalPos>0){wrapper.style.left=finalPos+"px"}else{wrapper.style.setProperty("--popover-arrow-offset",(wrapperPos.right-pos.right+4)+"px",)}wrapper.style.visibility="";window.CURRENT_TOOLTIP_ELEMENT=wrapper;window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE=e;clearTooltipHoverTimeout(window.CURRENT_TOOLTIP_ELEMENT);wrapper.onpointerenter=ev=>{if(ev.pointerType!=="mouse"){return}clearTooltipHoverTimeout(e)};wrapper.onpointerleave=ev=>{if(ev.pointerType!=="mouse"){return}if(!e.TOOLTIP_FORCE_VISIBLE&&!e.contains(ev.relatedTarget)){setTooltipHoverTimeout(e,false);addClass(wrapper,"fade-out")}}}function setTooltipHoverTimeout(element,show){clearTooltipHoverTimeout(element);if(!show&&!window.CURRENT_TOOLTIP_ELEMENT){return}if(show&&window.CURRENT_TOOLTIP_ELEMENT){return}if(window.CURRENT_TOOLTIP_ELEMENT&&window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE!==element){return}element.TOOLTIP_HOVER_TIMEOUT=setTimeout(()=>{if(show){showTooltip(element)}else if(!element.TOOLTIP_FORCE_VISIBLE){hideTooltip(false)}},show?window.RUSTDOC_TOOLTIP_HOVER_MS:window.RUSTDOC_TOOLTIP_HOVER_EXIT_MS)}function clearTooltipHoverTimeout(element){if(element.TOOLTIP_HOVER_TIMEOUT!==undefined){removeClass(window.CURRENT_TOOLTIP_ELEMENT,"fade-out");clearTimeout(element.TOOLTIP_HOVER_TIMEOUT);delete element.TOOLTIP_HOVER_TIMEOUT}}function tooltipBlurHandler(event){if(window.CURRENT_TOOLTIP_ELEMENT&&!window.CURRENT_TOOLTIP_ELEMENT.contains(document.activeElement)&&!window.CURRENT_TOOLTIP_ELEMENT.contains(event.relatedTarget)&&!window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.contains(document.activeElement)&&!window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.contains(event.relatedTarget)){setTimeout(()=>hideTooltip(false),0)}}function hideTooltip(focus){if(window.CURRENT_TOOLTIP_ELEMENT){if(window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.TOOLTIP_FORCE_VISIBLE){if(focus){window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.focus()}window.CURRENT_TOOLTIP_ELEMENT.TOOLTIP_BASE.TOOLTIP_FORCE_VISIBLE=false}const body=document.getElementsByTagName("body")[0];body.removeChild(window.CURRENT_TOOLTIP_ELEMENT);clearTooltipHoverTimeout(window.CURRENT_TOOLTIP_ELEMENT);window.CURRENT_TOOLTIP_ELEMENT=null}}onEachLazy(document.getElementsByClassName("tooltip"),e=>{e.onclick=()=>{e.TOOLTIP_FORCE_VISIBLE=e.TOOLTIP_FORCE_VISIBLE?false:true;if(window.CURRENT_TOOLTIP_ELEMENT&&!e.TOOLTIP_FORCE_VISIBLE){hideTooltip(true)}else{showTooltip(e);window.CURRENT_TOOLTIP_ELEMENT.setAttribute("tabindex","0");window.CURRENT_TOOLTIP_ELEMENT.focus();window.CURRENT_TOOLTIP_ELEMENT.onblur=tooltipBlurHandler}return false};e.onpointerenter=ev=>{if(ev.pointerType!=="mouse"){return}setTooltipHoverTimeout(e,true)};e.onpointermove=ev=>{if(ev.pointerType!=="mouse"){return}setTooltipHoverTimeout(e,true)};e.onpointerleave=ev=>{if(ev.pointerType!=="mouse"){return}if(!e.TOOLTIP_FORCE_VISIBLE&&window.CURRENT_TOOLTIP_ELEMENT&&!window.CURRENT_TOOLTIP_ELEMENT.contains(ev.relatedTarget)){setTooltipHoverTimeout(e,false);addClass(window.CURRENT_TOOLTIP_ELEMENT,"fade-out")}}});const sidebar_menu_toggle=document.getElementsByClassName("sidebar-menu-toggle")[0];if(sidebar_menu_toggle){sidebar_menu_toggle.addEventListener("click",()=>{const sidebar=document.getElementsByClassName("sidebar")[0];if(!hasClass(sidebar,"shown")){showSidebar()}else{hideSidebar()}})}function helpBlurHandler(event){blurHandler(event,getHelpButton(),window.hidePopoverMenus)}function buildHelpMenu(){const book_info=document.createElement("span");const channel=getVar("channel");book_info.className="top";book_info.innerHTML=`You can find more information in \
+the rustdoc book.`;const shortcuts=[["?","Show this help dialog"],["S / /","Focus the search field"],["↑","Move up in search results"],["↓","Move down in search results"],["← / →","Switch result tab (when results focused)"],["⏎","Go to active search result"],["+","Expand all sections"],["-","Collapse all sections"],].map(x=>"Keyboard Shortcuts
- "+shortcuts+"
fn:) to \
+ restrict the search to a given item kind.","Accepted kinds are: fn, mod, struct, \
+ enum, trait, type, macro, \
+ and const.","Search functions by type signature (e.g., vec -> usize or \
+ -> vec or String, enum:Cow -> bool)","You can look for items with an exact name by putting double quotes around \
+ your request: \"string\"","Look for functions that accept or return \
+ slices and \
+ arrays by writing \
+ square brackets (e.g., -> [u8] or [] -> Option)","Look for items inside another one by searching for a path: vec::Vec",].map(x=>""+x+"
").join("");const div_infos=document.createElement("div");addClass(div_infos,"infos");div_infos.innerHTML="Search Tricks
"+infos;const rustdoc_version=document.createElement("span");rustdoc_version.className="bottom";const rustdoc_version_code=document.createElement("code");rustdoc_version_code.innerText="rustdoc "+getVar("rustdoc-version");rustdoc_version.appendChild(rustdoc_version_code);const container=document.createElement("div");if(!isHelpPage){container.className="popover"}container.id="help";container.style.display="none";const side_by_side=document.createElement("div");side_by_side.className="side-by-side";side_by_side.appendChild(div_shortcuts);side_by_side.appendChild(div_infos);container.appendChild(book_info);container.appendChild(side_by_side);container.appendChild(rustdoc_version);if(isHelpPage){const help_section=document.createElement("section");help_section.appendChild(container);document.getElementById("main-content").appendChild(help_section);container.style.display="block"}else{const help_button=getHelpButton();help_button.appendChild(container);container.onblur=helpBlurHandler;help_button.onblur=helpBlurHandler;help_button.children[0].onblur=helpBlurHandler}return container}window.hideAllModals=switchFocus=>{hideSidebar();window.hidePopoverMenus();hideTooltip(switchFocus)};window.hidePopoverMenus=()=>{onEachLazy(document.querySelectorAll(".search-form .popover"),elem=>{elem.style.display="none"})};function getHelpMenu(buildNeeded){let menu=getHelpButton().querySelector(".popover");if(!menu&&buildNeeded){menu=buildHelpMenu()}return menu}function showHelp(){getHelpButton().querySelector("a").focus();const menu=getHelpMenu(true);if(menu.style.display==="none"){window.hideAllModals();menu.style.display=""}}if(isHelpPage){showHelp();document.querySelector(`#${HELP_BUTTON_ID} > a`).addEventListener("click",event=>{const target=event.target;if(target.tagName!=="A"||target.parentElement.id!==HELP_BUTTON_ID||event.ctrlKey||event.altKey||event.metaKey){return}event.preventDefault()})}else{document.querySelector(`#${HELP_BUTTON_ID} > a`).addEventListener("click",event=>{const target=event.target;if(target.tagName!=="A"||target.parentElement.id!==HELP_BUTTON_ID||event.ctrlKey||event.altKey||event.metaKey){return}event.preventDefault();const menu=getHelpMenu(true);const shouldShowHelp=menu.style.display==="none";if(shouldShowHelp){showHelp()}else{window.hidePopoverMenus()}})}setMobileTopbar();addSidebarItems();addSidebarCrates();onHashChange(null);window.addEventListener("hashchange",onHashChange);searchState.setup()}());(function(){const SIDEBAR_MIN=100;const SIDEBAR_MAX=500;const RUSTDOC_MOBILE_BREAKPOINT=700;const BODY_MIN=400;const SIDEBAR_VANISH_THRESHOLD=SIDEBAR_MIN/2;const sidebarButton=document.getElementById("sidebar-button");if(sidebarButton){sidebarButton.addEventListener("click",e=>{removeClass(document.documentElement,"hide-sidebar");updateLocalStorage("hide-sidebar","false");if(document.querySelector(".rustdoc.src")){window.rustdocToggleSrcSidebar()}e.preventDefault()})}let currentPointerId=null;let desiredSidebarSize=null;let pendingSidebarResizingFrame=false;const resizer=document.querySelector(".sidebar-resizer");const sidebar=document.querySelector(".sidebar");if(!resizer||!sidebar){return}const isSrcPage=hasClass(document.body,"src");function hideSidebar(){if(isSrcPage){window.rustdocCloseSourceSidebar();updateLocalStorage("src-sidebar-width",null);document.documentElement.style.removeProperty("--src-sidebar-width");sidebar.style.removeProperty("--src-sidebar-width");resizer.style.removeProperty("--src-sidebar-width")}else{addClass(document.documentElement,"hide-sidebar");updateLocalStorage("hide-sidebar","true");updateLocalStorage("desktop-sidebar-width",null);document.documentElement.style.removeProperty("--desktop-sidebar-width");sidebar.style.removeProperty("--desktop-sidebar-width");resizer.style.removeProperty("--desktop-sidebar-width")}}function showSidebar(){if(isSrcPage){window.rustdocShowSourceSidebar()}else{removeClass(document.documentElement,"hide-sidebar");updateLocalStorage("hide-sidebar","false")}}function changeSidebarSize(size){if(isSrcPage){updateLocalStorage("src-sidebar-width",size);sidebar.style.setProperty("--src-sidebar-width",size+"px");resizer.style.setProperty("--src-sidebar-width",size+"px")}else{updateLocalStorage("desktop-sidebar-width",size);sidebar.style.setProperty("--desktop-sidebar-width",size+"px");resizer.style.setProperty("--desktop-sidebar-width",size+"px")}}function isSidebarHidden(){return isSrcPage?!hasClass(document.documentElement,"src-sidebar-expanded"):hasClass(document.documentElement,"hide-sidebar")}function resize(e){if(currentPointerId===null||currentPointerId!==e.pointerId){return}e.preventDefault();const pos=e.clientX-3;if(pos\
+${item.alias} - see \
+
`}resultName.insertAdjacentHTML("beforeend",`${alias}\
+${item.displayPath}${name}\
+
`);const description=document.createElement("div");description.className="desc";description.insertAdjacentHTML("beforeend",item.desc);link.appendChild(description);output.appendChild(link)}}else if(query.error===null){output.className="search-failed"+extraClass;output.innerHTML="No results :("+"Try on DuckDuckGo?
"+"Or try looking in one of these:
- The Rust Reference "+" for technical details about the language.
- Rust By "+"Example for expository code examples.
- The Rust Book for "+"introductions to language features and the language itself.
- Docs.rs for documentation of crates released on"+" crates.io.
Results${crates}
`;if(results.query.error!==null){const error=results.query.error;error.forEach((value,index)=>{value=value.split("<").join("<").split(">").join(">");if(index%2!==0){error[index]=`${value.replaceAll(" ", " ")}`}else{error[index]=value}});output+=`Query parser error: "${error.join("")}".
`;output+=""+makeTabHeader(0,"In Names",ret_others[1])+"
";currentTab=0}else if(results.query.foundElems<=1&&results.query.returned.length===0){output+=""+makeTabHeader(0,"In Names",ret_others[1])+makeTabHeader(1,"In Parameters",ret_in_args[1])+makeTabHeader(2,"In Return Types",ret_returned[1])+"
"}else{const signatureTabTitle=results.query.elems.length===0?"In Function Return Types":results.query.returned.length===0?"In Function Parameters":"In Function Signatures";output+=""+makeTabHeader(0,signatureTabTitle,ret_others[1])+"
";currentTab=0}if(results.query.correction!==null){const orig=results.query.returned.length>0?results.query.returned[0].name:results.query.elems[0].name;output+=""+`Type "${orig}" not found. `+"Showing results for closest type name "+`"${results.query.correction}" instead.
`}if(results.query.proposeCorrectionFrom!==null){const orig=results.query.proposeCorrectionFrom;const targ=results.query.proposeCorrectionTo;output+=""+`Type "${orig}" not found and used as generic parameter. `+`Consider searching for "${targ}" instead.
`}const resultsElem=document.createElement("div");resultsElem.id="results";resultsElem.appendChild(ret_others[0]);resultsElem.appendChild(ret_in_args[0]);resultsElem.appendChild(ret_returned[0]);search.innerHTML=output;const crateSearch=document.getElementById("crate-search");if(crateSearch){crateSearch.addEventListener("input",updateCrate)}search.appendChild(resultsElem);searchState.showResults(search);const elems=document.getElementById("search-tabs").childNodes;searchState.focusedByTab=[];let i=0;for(const elem of elems){const j=i;elem.onclick=()=>printTab(j);searchState.focusedByTab.push(null);i+=1}printTab(currentTab)}function updateSearchHistory(url){if(!browserSupportsHistoryApi()){return}const params=searchState.getQueryStringParams();if(!history.state&&!params.search){history.pushState(null,"",url)}else{history.replaceState(null,"",url)}}async function search(forced){const query=parseQuery(searchState.input.value.trim());let filterCrates=getFilterCrates();if(!forced&&query.userQuery===currentResults){if(query.userQuery.length>0){putBackSearch()}return}searchState.setLoadingSearch();const params=searchState.getQueryStringParams();if(filterCrates===null&¶ms["filter-crate"]!==undefined){filterCrates=params["filter-crate"]}searchState.title="Results for "+query.original+" - Rust";updateSearchHistory(buildUrl(query.original,filterCrates));await showResults(await execQuery(query,filterCrates,window.currentCrate),params.go_to_first,filterCrates)}function buildItemSearchTypeAll(types,lowercasePaths){return types.length>0?types.map(type=>buildItemSearchType(type,lowercasePaths)):EMPTY_GENERICS_ARRAY}const EMPTY_BINDINGS_MAP=new Map();const EMPTY_GENERICS_ARRAY=[];let TYPES_POOL=new Map();function buildItemSearchType(type,lowercasePaths,isAssocType){const PATH_INDEX_DATA=0;const GENERICS_DATA=1;const BINDINGS_DATA=2;let pathIndex,generics,bindings;if(typeof type==="number"){pathIndex=type;generics=EMPTY_GENERICS_ARRAY;bindings=EMPTY_BINDINGS_MAP}else{pathIndex=type[PATH_INDEX_DATA];generics=buildItemSearchTypeAll(type[GENERICS_DATA],lowercasePaths,);if(type.length>BINDINGS_DATA&&type[BINDINGS_DATA].length>0){bindings=new Map(type[BINDINGS_DATA].map(binding=>{const[assocType,constraints]=binding;return[buildItemSearchType(assocType,lowercasePaths,true).id,buildItemSearchTypeAll(constraints,lowercasePaths),]}))}else{bindings=EMPTY_BINDINGS_MAP}}let result;if(pathIndex<0){result={id:pathIndex,ty:TY_GENERIC,path:null,exactPath:null,generics,bindings,}}else if(pathIndex===0){result={id:null,ty:null,path:null,exactPath:null,generics,bindings,}}else{const item=lowercasePaths[pathIndex-1];result={id:buildTypeMapIndex(item.name,isAssocType),ty:item.ty,path:item.path,exactPath:item.exactPath,generics,bindings,}}const cr=TYPES_POOL.get(result.id);if(cr){if(cr.generics.length===result.generics.length&&cr.generics!==result.generics&&cr.generics.every((x,i)=>result.generics[i]===x)){result.generics=cr.generics}if(cr.bindings.size===result.bindings.size&&cr.bindings!==result.bindings){let ok=true;for(const[k,v]of cr.bindings.entries()){const v2=result.bindings.get(v);if(!v2){ok=false;break}if(v!==v2&&v.length===v2.length&&v.every((x,i)=>v2[i]===x)){result.bindings.set(k,v)}else if(v!==v2){ok=false;break}}if(ok){result.bindings=cr.bindings}}if(cr.ty===result.ty&&cr.path===result.path&&cr.bindings===result.bindings&&cr.generics===result.generics&&cr.ty===result.ty){return cr}}TYPES_POOL.set(result.id,result);return result}function buildFunctionSearchTypeCallback(lowercasePaths){return functionSearchType=>{if(functionSearchType===0){return null}const INPUTS_DATA=0;const OUTPUT_DATA=1;let inputs,output;if(typeof functionSearchType[INPUTS_DATA]==="number"){inputs=[buildItemSearchType(functionSearchType[INPUTS_DATA],lowercasePaths)]}else{inputs=buildItemSearchTypeAll(functionSearchType[INPUTS_DATA],lowercasePaths,)}if(functionSearchType.length>1){if(typeof functionSearchType[OUTPUT_DATA]==="number"){output=[buildItemSearchType(functionSearchType[OUTPUT_DATA],lowercasePaths)]}else{output=buildItemSearchTypeAll(functionSearchType[OUTPUT_DATA],lowercasePaths,)}}else{output=[]}const where_clause=[];const l=functionSearchType.length;for(let i=2;i
+
`}else{const checked=setting["default"]===true?" checked":"";output+=`\
+${setting_name}
+ `;onEach(setting["options"],option=>{const checked=option===setting["default"]?" checked":"";const full=`${js_data_name}-${option.replace(/ /g,"-")}`;output+=`\
+ `});output+=`\
+
+\
+ \
+
`}}return output}function buildSettingsPage(){const theme_names=getVar("themes").split(",").filter(t=>t);theme_names.push("light","dark","ayu");const settings=[{"name":"Theme","js_name":"theme","default":"system preference","options":theme_names.concat("system preference"),},{"name":"Preferred light theme","js_name":"preferred-light-theme","default":"light","options":theme_names,},{"name":"Preferred dark theme","js_name":"preferred-dark-theme","default":"dark","options":theme_names,},{"name":"Auto-hide item contents for large items","js_name":"auto-hide-large-items","default":true,},{"name":"Auto-hide item methods' documentation","js_name":"auto-hide-method-docs","default":false,},{"name":"Auto-hide trait implementation documentation","js_name":"auto-hide-trait-implementations","default":false,},{"name":"Directly go to item in search if there is only one result","js_name":"go-to-only-result","default":false,},{"name":"Show line numbers on code examples","js_name":"line-numbers","default":false,},{"name":"Hide persistent navigation bar","js_name":"hide-sidebar","default":false,},{"name":"Disable keyboard shortcuts","js_name":"disable-shortcuts","default":false,},];const elementKind=isSettingsPage?"section":"div";const innerHTML=`${buildSettingsPageSections(settings)}
`;const el=document.createElement(elementKind);el.id="settings";if(!isSettingsPage){el.className="popover"}el.innerHTML=innerHTML;if(isSettingsPage){document.getElementById(MAIN_ID).appendChild(el)}else{el.setAttribute("tabindex","-1");getSettingsButton().appendChild(el)}return el}const settingsMenu=buildSettingsPage();function displaySettings(){settingsMenu.style.display="";onEachLazy(settingsMenu.querySelectorAll("input[type='checkbox']"),el=>{const val=getSettingValue(el.id);const checked=val==="true";if(checked!==el.checked&&val!==null){el.checked=checked}})}function settingsBlurHandler(event){blurHandler(event,getSettingsButton(),window.hidePopoverMenus)}if(isSettingsPage){getSettingsButton().onclick=event=>{event.preventDefault()}}else{const settingsButton=getSettingsButton();const settingsMenu=document.getElementById("settings");settingsButton.onclick=event=>{if(settingsMenu.contains(event.target)){return}event.preventDefault();const shouldDisplaySettings=settingsMenu.style.display==="none";window.hideAllModals();if(shouldDisplaySettings){displaySettings()}};settingsButton.onblur=settingsBlurHandler;settingsButton.querySelector("a").onblur=settingsBlurHandler;onEachLazy(settingsMenu.querySelectorAll("input"),el=>{el.onblur=settingsBlurHandler});settingsMenu.onblur=settingsBlurHandler}setTimeout(()=>{setEvents(settingsMenu);if(!isSettingsPage){displaySettings()}removeClass(getSettingsButton(),"rotate")},0)})()
\ No newline at end of file
diff --git a/doc/static.files/src-script-e66d777a5a92e9b2.js b/doc/static.files/src-script-e66d777a5a92e9b2.js
new file mode 100644
index 00000000..d0aebb85
--- /dev/null
+++ b/doc/static.files/src-script-e66d777a5a92e9b2.js
@@ -0,0 +1 @@
+"use strict";(function(){const rootPath=getVar("root-path");const NAME_OFFSET=0;const DIRS_OFFSET=1;const FILES_OFFSET=2;const RUSTDOC_MOBILE_BREAKPOINT=700;function closeSidebarIfMobile(){if(window.innerWidthwhere\n T: Send,
",1,["basis::list::stack::Stack"]]],
+"rustlings":[["impl Send for Subcommands",1,["rustlings::Subcommands"]],["impl Send for WatchStatus",1,["rustlings::WatchStatus"]],["impl Send for Mode",1,["rustlings::exercise::Mode"]],["impl Send for State",1,["rustlings::exercise::State"]],["impl Send for RunMode",1,["rustlings::verify::RunMode"]],["impl Send for ContextLine",1,["rustlings::exercise::ContextLine"]],["impl Send for Exercise",1,["rustlings::exercise::Exercise"]],["impl Send for ExerciseList",1,["rustlings::exercise::ExerciseList"]],["impl Send for ExerciseOutput",1,["rustlings::exercise::ExerciseOutput"]],["impl Send for FileHandle",1,["rustlings::exercise::FileHandle"]],["impl Send for Args",1,["rustlings::Args"]],["impl Send for HintArgs",1,["rustlings::HintArgs"]],["impl Send for ListArgs",1,["rustlings::ListArgs"]],["impl Send for RunArgs",1,["rustlings::RunArgs"]],["impl Send for VerifyArgs",1,["rustlings::VerifyArgs"]],["impl Send for WatchArgs",1,["rustlings::WatchArgs"]],["impl<'a> Send for CompiledExercise<'a>",1,["rustlings::exercise::CompiledExercise"]]]
+};if (window.register_implementors) {window.register_implementors(implementors);} else {window.pending_implementors = implementors;}})()
\ No newline at end of file
diff --git a/doc/trait.impl/core/marker/trait.StructuralPartialEq.js b/doc/trait.impl/core/marker/trait.StructuralPartialEq.js
new file mode 100644
index 00000000..baead6d7
--- /dev/null
+++ b/doc/trait.impl/core/marker/trait.StructuralPartialEq.js
@@ -0,0 +1,3 @@
+(function() {var implementors = {
+"rustlings":[["impl StructuralPartialEq for Subcommands"],["impl StructuralPartialEq for State"],["impl StructuralPartialEq for ContextLine"],["impl StructuralPartialEq for Args"],["impl StructuralPartialEq for HintArgs"],["impl StructuralPartialEq for ListArgs"],["impl StructuralPartialEq for RunArgs"],["impl StructuralPartialEq for VerifyArgs"],["impl StructuralPartialEq for WatchArgs"]]
+};if (window.register_implementors) {window.register_implementors(implementors);} else {window.pending_implementors = implementors;}})()
\ No newline at end of file
diff --git a/doc/trait.impl/core/marker/trait.Sync.js b/doc/trait.impl/core/marker/trait.Sync.js
new file mode 100644
index 00000000..983d76e6
--- /dev/null
+++ b/doc/trait.impl/core/marker/trait.Sync.js
@@ -0,0 +1,4 @@
+(function() {var implementors = {
+"basis":[["impl<T> Sync for Stack<T>where\n T: Sync,
",1,["basis::list::stack::Stack"]]],
+"rustlings":[["impl Sync for Subcommands",1,["rustlings::Subcommands"]],["impl Sync for WatchStatus",1,["rustlings::WatchStatus"]],["impl Sync for Mode",1,["rustlings::exercise::Mode"]],["impl Sync for State",1,["rustlings::exercise::State"]],["impl Sync for RunMode",1,["rustlings::verify::RunMode"]],["impl Sync for ContextLine",1,["rustlings::exercise::ContextLine"]],["impl Sync for Exercise",1,["rustlings::exercise::Exercise"]],["impl Sync for ExerciseList",1,["rustlings::exercise::ExerciseList"]],["impl Sync for ExerciseOutput",1,["rustlings::exercise::ExerciseOutput"]],["impl Sync for FileHandle",1,["rustlings::exercise::FileHandle"]],["impl Sync for Args",1,["rustlings::Args"]],["impl Sync for HintArgs",1,["rustlings::HintArgs"]],["impl Sync for ListArgs",1,["rustlings::ListArgs"]],["impl Sync for RunArgs",1,["rustlings::RunArgs"]],["impl Sync for VerifyArgs",1,["rustlings::VerifyArgs"]],["impl Sync for WatchArgs",1,["rustlings::WatchArgs"]],["impl<'a> Sync for CompiledExercise<'a>",1,["rustlings::exercise::CompiledExercise"]]]
+};if (window.register_implementors) {window.register_implementors(implementors);} else {window.pending_implementors = implementors;}})()
\ No newline at end of file
diff --git a/doc/trait.impl/core/marker/trait.Unpin.js b/doc/trait.impl/core/marker/trait.Unpin.js
new file mode 100644
index 00000000..2bf6cc6c
--- /dev/null
+++ b/doc/trait.impl/core/marker/trait.Unpin.js
@@ -0,0 +1,4 @@
+(function() {var implementors = {
+"basis":[["impl<T> Unpin for Stack<T>",1,["basis::list::stack::Stack"]]],
+"rustlings":[["impl Unpin for Subcommands",1,["rustlings::Subcommands"]],["impl Unpin for WatchStatus",1,["rustlings::WatchStatus"]],["impl Unpin for Mode",1,["rustlings::exercise::Mode"]],["impl Unpin for State",1,["rustlings::exercise::State"]],["impl Unpin for RunMode",1,["rustlings::verify::RunMode"]],["impl Unpin for ContextLine",1,["rustlings::exercise::ContextLine"]],["impl Unpin for Exercise",1,["rustlings::exercise::Exercise"]],["impl Unpin for ExerciseList",1,["rustlings::exercise::ExerciseList"]],["impl Unpin for ExerciseOutput",1,["rustlings::exercise::ExerciseOutput"]],["impl Unpin for FileHandle",1,["rustlings::exercise::FileHandle"]],["impl Unpin for Args",1,["rustlings::Args"]],["impl Unpin for HintArgs",1,["rustlings::HintArgs"]],["impl Unpin for ListArgs",1,["rustlings::ListArgs"]],["impl Unpin for RunArgs",1,["rustlings::RunArgs"]],["impl Unpin for VerifyArgs",1,["rustlings::VerifyArgs"]],["impl Unpin for WatchArgs",1,["rustlings::WatchArgs"]],["impl<'a> Unpin for CompiledExercise<'a>",1,["rustlings::exercise::CompiledExercise"]]]
+};if (window.register_implementors) {window.register_implementors(implementors);} else {window.pending_implementors = implementors;}})()
\ No newline at end of file
diff --git a/doc/trait.impl/core/ops/drop/trait.Drop.js b/doc/trait.impl/core/ops/drop/trait.Drop.js
new file mode 100644
index 00000000..d4ac59c0
--- /dev/null
+++ b/doc/trait.impl/core/ops/drop/trait.Drop.js
@@ -0,0 +1,4 @@
+(function() {var implementors = {
+"basis":[["impl<T> Drop for Stack<T>"]],
+"rustlings":[["impl Drop for FileHandle"]]
+};if (window.register_implementors) {window.register_implementors(implementors);} else {window.pending_implementors = implementors;}})()
\ No newline at end of file
diff --git a/doc/trait.impl/core/panic/unwind_safe/trait.RefUnwindSafe.js b/doc/trait.impl/core/panic/unwind_safe/trait.RefUnwindSafe.js
new file mode 100644
index 00000000..66b6e48f
--- /dev/null
+++ b/doc/trait.impl/core/panic/unwind_safe/trait.RefUnwindSafe.js
@@ -0,0 +1,4 @@
+(function() {var implementors = {
+"basis":[["impl<T> RefUnwindSafe for Stack<T>where\n T: RefUnwindSafe,
",1,["basis::list::stack::Stack"]]],
+"rustlings":[["impl RefUnwindSafe for Subcommands",1,["rustlings::Subcommands"]],["impl RefUnwindSafe for WatchStatus",1,["rustlings::WatchStatus"]],["impl RefUnwindSafe for Mode",1,["rustlings::exercise::Mode"]],["impl RefUnwindSafe for State",1,["rustlings::exercise::State"]],["impl RefUnwindSafe for RunMode",1,["rustlings::verify::RunMode"]],["impl RefUnwindSafe for ContextLine",1,["rustlings::exercise::ContextLine"]],["impl RefUnwindSafe for Exercise",1,["rustlings::exercise::Exercise"]],["impl RefUnwindSafe for ExerciseList",1,["rustlings::exercise::ExerciseList"]],["impl RefUnwindSafe for ExerciseOutput",1,["rustlings::exercise::ExerciseOutput"]],["impl RefUnwindSafe for FileHandle",1,["rustlings::exercise::FileHandle"]],["impl RefUnwindSafe for Args",1,["rustlings::Args"]],["impl RefUnwindSafe for HintArgs",1,["rustlings::HintArgs"]],["impl RefUnwindSafe for ListArgs",1,["rustlings::ListArgs"]],["impl RefUnwindSafe for RunArgs",1,["rustlings::RunArgs"]],["impl RefUnwindSafe for VerifyArgs",1,["rustlings::VerifyArgs"]],["impl RefUnwindSafe for WatchArgs",1,["rustlings::WatchArgs"]],["impl<'a> RefUnwindSafe for CompiledExercise<'a>",1,["rustlings::exercise::CompiledExercise"]]]
+};if (window.register_implementors) {window.register_implementors(implementors);} else {window.pending_implementors = implementors;}})()
\ No newline at end of file
diff --git a/doc/trait.impl/core/panic/unwind_safe/trait.UnwindSafe.js b/doc/trait.impl/core/panic/unwind_safe/trait.UnwindSafe.js
new file mode 100644
index 00000000..0bf0116e
--- /dev/null
+++ b/doc/trait.impl/core/panic/unwind_safe/trait.UnwindSafe.js
@@ -0,0 +1,4 @@
+(function() {var implementors = {
+"basis":[["impl<T> UnwindSafe for Stack<T>where\n T: UnwindSafe,
",1,["basis::list::stack::Stack"]]],
+"rustlings":[["impl UnwindSafe for Subcommands",1,["rustlings::Subcommands"]],["impl UnwindSafe for WatchStatus",1,["rustlings::WatchStatus"]],["impl UnwindSafe for Mode",1,["rustlings::exercise::Mode"]],["impl UnwindSafe for State",1,["rustlings::exercise::State"]],["impl UnwindSafe for RunMode",1,["rustlings::verify::RunMode"]],["impl UnwindSafe for ContextLine",1,["rustlings::exercise::ContextLine"]],["impl UnwindSafe for Exercise",1,["rustlings::exercise::Exercise"]],["impl UnwindSafe for ExerciseList",1,["rustlings::exercise::ExerciseList"]],["impl UnwindSafe for ExerciseOutput",1,["rustlings::exercise::ExerciseOutput"]],["impl UnwindSafe for FileHandle",1,["rustlings::exercise::FileHandle"]],["impl UnwindSafe for Args",1,["rustlings::Args"]],["impl UnwindSafe for HintArgs",1,["rustlings::HintArgs"]],["impl UnwindSafe for ListArgs",1,["rustlings::ListArgs"]],["impl UnwindSafe for RunArgs",1,["rustlings::RunArgs"]],["impl UnwindSafe for VerifyArgs",1,["rustlings::VerifyArgs"]],["impl UnwindSafe for WatchArgs",1,["rustlings::WatchArgs"]],["impl<'a> UnwindSafe for CompiledExercise<'a>",1,["rustlings::exercise::CompiledExercise"]]]
+};if (window.register_implementors) {window.register_implementors(implementors);} else {window.pending_implementors = implementors;}})()
\ No newline at end of file
diff --git a/doc/trait.impl/serde/de/trait.Deserialize.js b/doc/trait.impl/serde/de/trait.Deserialize.js
new file mode 100644
index 00000000..5e3df044
--- /dev/null
+++ b/doc/trait.impl/serde/de/trait.Deserialize.js
@@ -0,0 +1,3 @@
+(function() {var implementors = {
+"rustlings":[["impl<'de> Deserialize<'de> for Mode"],["impl<'de> Deserialize<'de> for Exercise"],["impl<'de> Deserialize<'de> for ExerciseList"]]
+};if (window.register_implementors) {window.register_implementors(implementors);} else {window.pending_implementors = implementors;}})()
\ No newline at end of file
diff --git a/editor.js b/editor.js
new file mode 100644
index 00000000..464790c4
--- /dev/null
+++ b/editor.js
@@ -0,0 +1,29 @@
+"use strict";
+window.editors = [];
+(function(editors) {
+ if (typeof(ace) === 'undefined' || !ace) {
+ return;
+ }
+
+ Array.from(document.querySelectorAll('.editable')).forEach(function(editable) {
+ let display_line_numbers = window.playground_line_numbers || false;
+
+ let editor = ace.edit(editable);
+ editor.setOptions({
+ highlightActiveLine: false,
+ showPrintMargin: false,
+ showLineNumbers: display_line_numbers,
+ showGutter: display_line_numbers,
+ maxLines: Infinity,
+ fontSize: "0.875em" // please adjust the font size of the code in general.css
+ });
+
+ editor.$blockScrolling = Infinity;
+
+ editor.getSession().setMode("ace/mode/rust");
+
+ editor.originalCode = editor.getValue();
+
+ editors.push(editor);
+ });
+})(window.editors);
diff --git a/elasticlunr.min.js b/elasticlunr.min.js
new file mode 100644
index 00000000..94b20dd2
--- /dev/null
+++ b/elasticlunr.min.js
@@ -0,0 +1,10 @@
+/**
+ * elasticlunr - http://weixsong.github.io
+ * Lightweight full-text search engine in Javascript for browser search and offline search. - 0.9.5
+ *
+ * Copyright (C) 2017 Oliver Nightingale
+ * Copyright (C) 2017 Wei Song
+ * MIT Licensed
+ * @license
+ */
+!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mark.min.js b/mark.min.js
new file mode 100644
index 00000000..16362318
--- /dev/null
+++ b/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ awesome-rust
+
:wrench: Rust prototypes.
+Crates
+ +Contributing
+Contributions are greatly appreciated. +Please fork this repository and open a pull request.
+Credits
+ +Contact
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rustBasicNotes.html b/rustBasicNotes.html
new file mode 100644
index 00000000..e6f56fc2
--- /dev/null
+++ b/rustBasicNotes.html
@@ -0,0 +1,3961 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ awesome-rust
+
:wrench: Rust prototypes.
+Crates
+ +Contributing
+Contributions are greatly appreciated. +Please fork this repository and open a pull request.
+Credits
+ +Contact
+
Rust Basic Notes
+Toolchain
+Installation
+curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
+Cargo
+Cargo Basic Commands
+cargo new hello_world
+cargo run
+cargo build
+cargo run --release
+cargo build --release
+cargo check
+cargo generate-lockfile
+cargo fmt --check
+cargo clippy
+cargo test
+cargo install cargo-edit
+cargo install cargo-release
+cargo install cargo-tarpaulin
+cargo install cargo-watch
+cargo install cargo-workspaces
+Cargo release configuration:
+[workspace.metadata.release]
+# cargo install cargo-release
+# cargo release -x
+sign-commit = true
+sign-tag = true
+release = false
+push = false
+publish = false
+shared-version = true
+pre-release-commit-message = "chore(release): {{version}}"
+post-release-commit-message = "chore(release): {{version}}"
+tag-message = "{{tag_name}}"
+Cargo Cache
+~/.cargo/:
-
+
config.toml: global configuration.
+credentials.toml:cargo loginrelated file.
+.crates.toml/.crates2.json: installed package information.
+bin/: installed binaries.
+git/: installed rust git repositories. +-
+
git/db/: installed git repositories.
+git/checkouts/: branches of git repositories.
+
+registry/:crates.iometadata and packages. +-
+
registry/index/: metadata git repository.
+registry/cache/: dependencies cache (.crategzip files).
+registry/src/: package source files.
+
+
Cargo Configuration
+Cargo.toml:
-
+
cargo-features: 只能用于nightly版本的feature.
+[package]: 定义项目(package)的元信息. +-
+
name: 名称.
+version: 版本.
+authors: 开发作者.
+edition: Rust edition..
+rust-version: 支持的最小化 Rust 版本.
+description: 描述.
+documentation: 文档 URL.
+readme: README 文件的路径.
+homepage: 主页 URL.
+repository: 源代码仓库的 URL.
+license: 开源协议 License..
+license-file: License 文件的路径..
+keywords: 项目的关键词.
+categories: 项目分类.
+workspace: 工作空间 workspace 的路径.
+build: 构建脚本的路径.
+links: 本地链接库的名称.
+exclude: 发布时排除的文件.
+include: 发布时包含的文件.
+publish: 用于阻止项目的发布.
+metadata: 额外的配置信息，用于提供给外部工具.
+default-run: [cargo run] 所使用的默认可执行文件( binary ).
+autobins: 禁止可执行文件的自动发现.
+autoexamples: 禁止示例文件的自动发现.
+autotests: 禁止测试文件的自动发现.
+autobenches: 禁止 bench 文件的自动发现.
+resolver: 设置依赖解析器( dependency resolver).
+
+- Cargo target configuration:
+
-
+
[lib]: Library target.
+[[bin]]: Binary target.
+[[example]]: Example target.
+[[test]]: Test target.
+[[bench]]: Benchmark target.
+
+ - Dependency tables:
+
-
+
[dependencies]: 项目依赖包.
+[dev-dependencies]: +用于 examples、tests 和 benchmarks 的依赖包.
+[build-dependencies]: 用于构建脚本的依赖包.
+[target]: 平台特定的依赖包.
+
+ [badges]: 维护状态.
+[features]:features可以用于条件编译.
+[patch]: 推荐使用的依赖覆盖方式.
+[profile]: 编译器设置和优化.
+[workspace]: 工作空间的定义.
+
GitHub Action
+-
+
- Use tool to speed up compilation. +
name: CI
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+
+env:
+ CARGO_TERM_COLOR: always
+
+jobs:
+ test:
+ name: Test Suite
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ - uses: actions-rs/cargo@v1
+ with:
+ command: test
+ args: --all-features --workspace
+
+ rustfmt:
+ name: Rustfmt
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ components: rustfmt
+ - name: Check formatting
+ uses: actions-rs/cargo@v1
+ with:
+ command: fmt
+ args: --all -- --check
+
+ clippy:
+ name: Clippy
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ components: clippy
+ - name: Clippy check
+ uses: actions-rs/cargo@v1
+ with:
+ command: clippy
+ args: --all-targets --all-features --workspace -- -D warnings
+
+ docs:
+ name: Docs
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ - name: Check documentation
+ env:
+ RUSTDOCFLAGS: -D warnings
+ uses: actions-rs/cargo@v1
+ with:
+ command: doc
+ args: --no-deps --document-private-items --all-features --workspace
+
+ publish-dry-run:
+ name: Publish dry run
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ - uses: actions-rs/cargo@v1
+ with:
+ command: publish
+ args: --dry-run
+
+ coverage:
+ name: Code coverage
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ - name: Run cargo-tarpaulin
+ uses: actions-rs/tarpaulin@v0.1
+ with:
+ args: --all-features --workspace --ignore-tests --out Lcov
+ - name: Upload to Coveralls
+ if: ${{ github.event_name == 'push' }}
+ uses: coverallsapp/github-action@v1
+ with:
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ path-to-lcov: ./lcov.info
+Ownership
+Copy Trait
+Copyable type (implement Copy trait):
-
+
- Integer type. +
- Bool type. +
- Float type. +
- Char type. +
- Copyable Tuple type, e.g
(i32, i32).
+ - Reference type (borrowing ownership). +
Most these types store on stack +(including reference type with vtable).
++fn main() { + // Primitive type. + let a = 5; + let b = a; + + // Reference type. + let x: &str = "hello, world"; + let y = x; + + // Deep clone on `non-Copy` type. + let s1 = String::from("hello"); + let s2 = s1.clone(); + + // Correct. + println!("a = {}, b = {}", a, b); + println!("x = {}, y = {}", x, y); + println!("s1 = {}, s2 = {}", s1, s2); +}
+fn main() { + let s1 = String::from("hello"); + let s2 = s1; + + // Error[E0382]: use of moved value: `s1`. + // Move occurs because `s1` has type `std::string::String`, + // which does not implement the `Copy` trait. + println!("{}, world!", s1); +}
Reference Type
+Borrowing ownership with reference type:
+-
+
- At same time, only one mutable reference or multiple immutable reference. +
- Reference should be valid (rustc will report dangling reference error). +
+fn main() { + let s1 = String::from("hello"); + let len = calculate_length(&s1); + println!("The length of '{}' is {}.", s1, len); +} + +fn calculate_length(s: &String) -> usize { + s.len() + // Leave function without drop `s`, + // due to `s` not owner string. +}
Mutable reference:
+-
+
- Only one mutable reference for a value in a scope). +
- Can't mutable borrow an already immutable borrowed value. +
+fn main() { + let mut s = String::from("hello"); + change(&mut s); +} + +fn change(some_string: &mut String) { + some_string.push_str(", world"); +}
+fn main() { + let mut s = String::from("hello"); + + let r1 = &s; + let r2 = &s; + let r3 = &mut s; + + // Error. + println!("{}, {} and {}", r1, r2, r3); + // End of r1 and r2 borrowing. + + // Correct. + let r4 = &mut s; + println!("{}", r4); +}
String Type
+&str string slice reference type:
-
+
- Borrowing type. +
- UTF-8 encode (1 ~ 4 bytes). +
- String literal is
&strtype.
+
+#![allow(unused)] +fn main() { +let s = String::from("hello world"); +let len = s.len(); + +let hello = &s[0..5]; +let world = &s[6..11]; +let slice1 = &s[0..2]; +let slice2 = &s[..2]; +let slice3 = &s[4..len]; +let slice4 = &s[4..]; +let slice5 = &s[0..len]; +let slice6 = &s[..]; +}
String type:
-
+
- Ownership type. +
- UTF-8 encode (1 ~ 4 bytes). +
+fn main() { + let mut s = String::new(); + s.push_str("hello,world"); + s.push('!'); + assert_eq!(s,"hello,world!"); + + let mut s = "hello,world".to_string(); + s.push('!'); + assert_eq!(s,"hello,world!"); + + let mut s = String::from("你好, 世界"); + s.push('!'); + assert_eq!(s,"你好, 世界!"); + + let s1 = String::from("hello,"); + let s2 = String::from("world!"); + let s3 = s1 + &s2; + assert_eq!(s3,"hello,world!"); + + for c in "中国人".chars() { + println!("{}", c); + } +}
Struct Type
++#![allow(unused)] +fn main() { +struct User { + active: bool, + username: String, + email: String, + sign_in_count: u64, +} + +fn build_user(email: String, username: String) -> User { + User { + email, + username, + active: true, + sign_in_count: 1, + } +} + +let user1 = User { + email: String::from("someone@example.com"), + username: String::from("username123"), + active: true, + sign_in_count: 1, +}; + +let user2 = User { + email: String::from("another@example.com"), + ..user1 +}; +}
Tuple Struct
++#![allow(unused)] +fn main() { +struct Color(i32, i32, i32); +struct Point(i32, i32, i32); +let black = Color(0, 0, 0); +let origin = Point(0, 0, 0); +}
newtype: Wrap type into tuple struct:
-
+
- Make code more readable. +
- Implement 3rd traits for 3rd types. +
- Hide internal details of types. +
+#![allow(unused)] +fn main() { +struct Meters(u32); +}
Unit-like Struct
++#![allow(unused)] +fn main() { +struct AlwaysEqual; +let subject = AlwaysEqual; +impl SomeTrait for AlwaysEqual {} +}
Enum Type
++enum Message { + Quit, + Move { x: i32, y: i32 }, + Write(String), + ChangeColor(i32, i32, i32), +} + +fn main() { + let m1 = Message::Quit; + let m2 = Message::Move{x: 1, y: 1}; + let m3 = Message::ChangeColor(255, 255, 0); +}
+#![allow(unused)] +fn main() { +enum Option<T> { + Some(T), + None, +} + +fn plus_one(x: Option<i32>) -> Option<i32> { + match x { + None => None, + Some(i) => Some(i + 1), + } +} + +let five = Some(5); +let six = plus_one(five); +let none = plus_one(None); +}
Array Type
++let a: [i32; 5] = [1, 2, 3, 4, 5]; +let b = [3; 5]; +let slice: &[i32] = &a[1..3]; +assert_eq!(slice, &[2, 3]); + +fn main() { + let one = [1, 2, 3]; + let two: [u8; 3] = [1, 2, 3]; + let blank1 = [0; 3]; + let blank2: [u8; 3] = [0; 3]; + + let arrays: [[u8; 3]; 4] = [one, two, blank1, blank2]; + + for a in &arrays { + print!("{:?}: ", a); + + for n in a.iter() { + print!("\t{} + 10 = {}", n, n+10); + } + + let mut sum = 0; + + for i in 0..a.len() { + sum += a[i]; + } + + println!("\t({:?} = {})", a, sum); + } +}
Type Alias
++#![allow(unused)] +fn main() { +type Meters = i32; + +let x: u32 = 5; +let y: Meters = 5; + +println!("x + y = {}", x + y); +}
+#![allow(unused)] +fn main() { +type Result<T> = std::result::Result<T, std::io::Error>; +type Thunk = Box<dyn Fn() + Send + 'static>; + +let f: Thunk = Box::new(|| println!("hi")); +fn takes_long_type(f: Thunk) {} +fn returns_long_type() -> Thunk {} +}
Type Conversion
+From Trait
++use std::convert::From; + +#[derive(Debug)] +struct Number { + value: i32, +} + +impl From<i32> for Number { + fn from(item: i32) -> Self { + Number { value: item } + } +} + +fn main() { + let num = Number::from(30); + println!("My number is {:?}", num); + + let int = 5; + let num: Number = int.into(); + println!("My number is {:?}", num); +}
+use std::convert::TryFrom; +use std::convert::TryInto; + +#[derive(Debug, PartialEq)] +struct EvenNumber(i32); + +impl TryFrom<i32> for EvenNumber { + type Error = (); + + fn try_from(value: i32) -> Result<Self, Self::Error> { + if value % 2 == 0 { + Ok(EvenNumber(value)) + } else { + Err(()) + } + } +} + +fn main() { + // TryFrom + assert_eq!(EvenNumber::try_from(8), Ok(EvenNumber(8))); + assert_eq!(EvenNumber::try_from(5), Err(())); + + // TryInto + let result: Result<EvenNumber, ()> = 8i32.try_into(); + assert_eq!(result, Ok(EvenNumber(8))); + let result: Result<EvenNumber, ()> = 5i32.try_into(); + assert_eq!(result, Err(())); +}
Explicit Type Conversion
++fn main() { + let a = 3.1 as i8; + let b = 100_i8 as i32; + let c = 'a' as u8; + println!("{}, {}, {}", a, b, c) + + let x: i16 = 1500; + let x_: u8 = match x.try_into() { + Ok(x1) => x1, + Err(e) => { + println!("{:?}", e.to_string()); + 0 + } + }; +}
Implicit Type Conversion
+target.method():
-
+
- Call by value:
T::method(target).
+ - Call by reference:
T::method(&target)orT::method(&mut target).
+ - Call by deref: when
T: Deref<Target = U>, then(&T).method() => (&U).method().
+ - Length-non-determined collection to length-determined slice. +
- Panic. +
+#![allow(unused)] +fn main() { +let array: Rc<Box<[T; 3]>> = ...; +let first_entry = array[0]; +// 1. `Index` trait grammar sugar: array[0] => array.index(0). +// 2. Call by: value: `Rc<Box<[T; 3]>>` not impl `Index` trait. +// 3. Call by reference: `&Rc<Box<[T; 3]>>` not impl `Index` trait. +// 4. Call by reference: `&mut Rc<Box<[T; 3]>>` not impl `Index` trait. +// 5. Call by deref -> Call by value: `Box<[T; 3]>` not impl `Index` trait. +// 6. Call by deref -> Call by reference: `&Box<[T; 3]>` not impl `Index` trait. +// 7. Call by deref -> Call by reference: `&mut Box<[T; 3]>` not impl `Index` trait. +// 8. Call by deref -> Call by deref: `[T; 3]` not impl `Index` trait. +// 9. `[T; 3]` => `[T]` impl `Index` trait. +}
Dynamically Sized Type
+DST:
+-
+
- DST 无法单独被使用, 必须要通过
&/Box/Rc来间接使用.
+ str,[T],dyn Trait.
+
+#![allow(unused)] +fn main() { +// Error! +let s1: str = "Hello there!"; +let s2: str = "How's it going?"; + +// Ok. +let s3: &str = "on?" +let s4: Box<str> = "Hello there!".into(); +}
+#![allow(unused)] +fn main() { +// Error! +fn my_function(n: usize) { + let array = [123; n]; +} +}
+#![allow(unused)] +fn main() { +fn foobar_1(thing: &dyn MyThing) {} // OK. +fn foobar_2(thing: Box<dyn MyThing>) {} // OK. +fn foobar_3(thing: Rc<dyn MyThing>) {} // OK. +fn foobar_4(thing: MyThing) {} // ERROR! +}
Sized Trait
+Implicit sized trait:
++#![allow(unused)] +fn main() { +fn generic<T>(t: T) {} +// Auto-transform to by Rust compiler +fn generic<T: Sized>(t: T) {} +}
Dynamic sized generics:
++#![allow(unused)] +fn main() { +fn generic<T: ?Sized>(t: &T) {} +}
Flow Control
+If Statement
+if expression:
+#![allow(unused)] +fn main() { +let number = if condition { + 5 +} else { + 6 +}; +}
if let expression:
+#![allow(unused)] +fn main() { +let o = Some(3); +let v = if let Some(x) = o { + x +} else { + 0 +}; +}
Loop Statement
+For Loop Statement
++#![allow(unused)] +fn main() { +for i in 1..=5 {} +for _ in 0..10 {} +for item in collection {} +for item in &collection {} +for item in &mut collection {} +for (i, v) in collection.iter().enumerate() {} +}
While Loop Statement
++fn main() { + let mut n = 0; + + while n <= 5 { + println!("{}!", n); + n = n + 1; + } +}
Loop Expression
++fn main() { + let mut counter = 0; + + let result = loop { + counter += 1; + + if counter == 10 { + break counter * 2; + } + }; + + println!("The result is {}", result); +}
Pattern Matching
++#![allow(unused)] +fn main() { +match target { + pattern1 => expression1, + pattern2 => { + statement1; + statement2; + expression2 + }, + _ => expression3 +} + +if let pattern = target { + statement; + expression +} + +while let pattern = target { + statement; +} +}
Enum Pattern Matching
++enum Action { + Say(String), + MoveTo(i32, i32), + ChangeColorRGB(u16, u16, u16), +} + +fn main() { + let actions = [ + Action::Say("Hello Rust".to_string()), + Action::MoveTo(1,2), + Action::ChangeColorRGB(255,255,0), + ]; + + for action in actions { + match action { + Action::Say(s) => { + println!("{}", s); + }, + Action::MoveTo(x, y) => { + println!("point from (0, 0) move to ({}, {})", x, y); + }, + Action::ChangeColorRGB(r, g, _) => { + println!("change color into '(r:{}, g:{}, b:0)', 'b' has been ignored", + r, g, + ); + } + } + } +}
Tuple Pattern Matching
++fn main() { + let numbers = (2, 4, 8, 16, 32); + + match numbers { + (first, .., last) => { + println!("Some numbers: {}, {}", first, last); + }, + } +}
Struct Pattern Matching
++struct Point { + x: i32, + y: i32, + z: i32, +} + +fn main() { + let p = Point { x: 0, y: 7, z: 0 }; + let Point { x: a, y: b, z: c } = p; + assert_eq!(0, a); + assert_eq!(7, b); + assert_eq!(0, c); + + let origin = Point { x: 0, y: 0, z: 0 }; + match origin { + Point { x, .. } => println!("x is {}", x), + } +}
+fn main() { + let p = Point { x: 0, y: 7 }; + + match p { + Point { x, y: 0 } => println!("On the x axis at {}", x), + Point { x: 0, y } => println!("On the y axis at {}", y), + Point { x, y } => println!("On neither axis: ({}, {})", x, y), + } +}
Match Guard
+Combine pattern matching and if expression:
+#![allow(unused)] +fn main() { +let num = Some(4); + +match num { + Some(x) if x < 5 => println!("less than five: {}", x), + Some(x) => println!("{}", x), + None => (), +} +}
Match Assignment
+Combine pattern matching and @ expression:
+#![allow(unused)] +fn main() { +enum Message { + Hello { id: i32 }, +} + +let msg = Message::Hello { id: 5 }; + +match msg { + Message::Hello { id: id_variable @ 3..=7 } => { + println!("Found an id in range: {}", id_variable) + }, + Message::Hello { id: 10..=12 } => { + println!("Found an id in another range") + }, + Message::Hello { id } => { + println!("Found some other id: {}", id) + }, +} +}
+struct Point { + x: i32, + y: i32, +} + +fn main() { + let p @ Point {x: px, y: py } = Point {x: 10, y: 23}; + println!("x: {}, y: {}", px, py); + println!("{:?}", p); + + let point = Point {x: 10, y: 5}; + if let p @ Point {x: 10, y} = point { + println!("x is 10 and y is {} in {:?}", y, p); + } else { + println!("x was not 10 :("); + } +}
Method
++#![allow(unused)] +fn main() { +struct Circle { + x: f64, + y: f64, + radius: f64, +} + +impl Circle { + fn new(x: f64, y: f64, radius: f64) -> Circle { + Circle { + x, + y, + radius, + } + } + + fn area(&self) -> f64 { + std::f64::consts::PI * (self.radius * self.radius) + } +} +}
+enum Message { + Quit, + Move { x: i32, y: i32 }, + Write(String), + ChangeColor(i32, i32, i32), +} + +impl Message { + fn call(&self) {} +} + +fn main() { + let m = Message::Write(String::from("hello")); + m.call(); +}
Self
+-
+
self: 所有权转移.
+&self: 不可变借用.
+&mut self: 可变借用.
+
+pub struct Rectangle { + width: u32, + height: u32, +} + +impl Rectangle { + pub fn new(width: u32, height: u32) -> Self { + Rectangle { width, height } + } + pub fn width(&self) -> u32 { + return self.width; + } + pub fn height(&self) -> u32 { + return self.height; + } +} + +fn main() { + let rect = Rectangle::new(30, 50); + println!("{}", rect.width()); + println!("{}", rect.height()); +}
Generics
++#![allow(unused)] +fn main() { +enum Option<T> { + Some(T), + None, +} + +enum Result<T, E> { + Ok(T), + Err(E), +} + +struct Point<T> { + x: T, + y: T, +} + +impl<T> Point<T> { + fn x(&self) -> &T { + &self.x + } + + fn mixup<U>(self, other: Point<U>) {} +} + +impl Point<f32> { + fn distance_from_origin(&self) -> f32 { + (self.x.powi(2) + self.y.powi(2)).sqrt() + } +} + + +fn add<T: std::ops::Add<T, Output = T>>(a:T, b:T) -> T { + a + b +} + +fn largest<T: PartialOrd>(list: &[T]) -> T {} +}
-
+
- TurboFish:
+
-
+
generics_struct::<T>::method().
+struct.generics_method::<T>().
+
+ - Use associated types in traits. +
Traits
++pub struct Post { + pub username: String, + pub content: String +} + +pub trait Summary { + fn summarize_author(&self) -> String; + + fn summarize(&self) -> String { + format!("(Read more from {}...)", self.summarize_author()) + } +} + +impl Summary for Post { + fn summarize_author(&self) -> String { + format!("@{}", self.username) + } +} + +fn main() { + let post = Post{username: "username".to_string(),content: "content".to_string()}; + println!("1 new post: {}", post.summarize()); +}
Orphan Rule
+Rust can’t implement external traits on external types:
+can’t implement the Display trait on Vec<T> in some_package crate,
+because Display and Vec<T> are both defined out of some_package.
+This restriction is part of a property of programs called coherence,
+ensures that other people’s code can’t break your code and vice versa.
Trait Bound
++#![allow(unused)] +fn main() { +fn notify(item: &impl Summary) {} +fn notify(item: &(impl Summary + Display)) {} +fn notify<T: Summary>(item: &T) {} +fn notify<T: Summary + Display>(item: &T) {} +fn notify<T, U>(t: &T, u: &U) -> i32 + where T: Display + Clone, + U: Clone + Debug +{} +}
+#![allow(unused)] +fn main() { +trait SomeTrait: BoundTrait {} +}
+#![allow(unused)] +fn main() { +// 可以对任何实现了 Display 特征的类型调用 ToString 特征中方法. +impl<T: Display> ToString for T {} +}
Trait Derive
++#![allow(unused)] +fn main() { +#[derive(Debug)] +#[derive(PartialEq)] +#[derive(Eq)] +#[derive(PartialOrd)] +#[derive(Ord)] +#[derive(Clone)] +#[derive(Copy)] +#[derive(Hash)] +#[derive(Default)] +}
+#![allow(unused)] +fn main() { +trait Person { + fn name(&self) -> String; +} + +trait Student: Person { + fn university(&self) -> String; +} + +trait Programmer { + fn fav_language(&self) -> String; +} + +trait CompSciStudent: Programmer + Student { + fn git_username(&self) -> String; +} + +fn comp_sci_student_greeting(student: &dyn CompSciStudent) -> String { + format!( + "My name is {} and I attend {}. My language is {}. My Git username is {}", + student.name(), + student.university(), + student.fav_language(), + student.git_username() + ) +} +}
Trait Object
+-
+
- Define trait object:
+
-
+
Box<dyn some_trait>.
+&dyn some_trait.
+
+ - A trait can have trait object only when
+it is
object safe: +-
+
- all methods can't return
Self.
+ - all methods can't be generics. +
+ - all methods can't return
- Trait object has
'staticlifetime.
+ - Trait object stand for dynamic distributing (runtime), +generics stand for static distributing (compile time). +
+trait Draw { + fn draw(&self) -> String; +} + +impl Draw for u8 { + fn draw(&self) -> String { + format!("u8: {}", *self) + } +} + +impl Draw for f64 { + fn draw(&self) -> String { + format!("f64: {}", *self) + } +} + +fn draw1(x: Box<dyn Draw>) { + x.draw(); +} + +fn draw2(x: &dyn Draw) { + x.draw(); +} + +fn main() { + let x = 1.1f64; + let y = 8u8; + + draw1(Box::new(x)); + draw1(Box::new(y)); + draw2(&x); + draw2(&y); +}
Associated Types
+Associated types make code become readable and concise:
++#![allow(unused)] +fn main() { +trait Container<A,B> { + fn contains(&self,a: A,b: B) -> bool; +} + +fn difference<A,B,C>(container: &C) -> i32 + where + C : Container<A,B> {} +}
+#![allow(unused)] +fn main() { +trait Container{ + type A; + type B; + fn contains(&self, a: &Self::A, b: &Self::B) -> bool; +} + +fn difference<C: Container>(container: &C) {} +}
For all generic trait,
+use associated types better than <T>.
Common Traits
+-
+
std::fmt::Display(better thanstd::string::ToString).
+std::fmt::Debug.
+std::ops::Add/Mul/Div/BitAnd/BitOr/Not/Neg: operators overload.
+std::ops::Fn/FnMut/FnOnce.
+std::ops::Deref.
+std::ops::Drop.
+std::clone::Clone.
+std::iter::Iterator.
+
std::prelude:
-
+
std::marker::{Copy, Send, Sized, Sync, Unpin}.
+std::ops::{Drop, Fn, FnMut, FnOnce}.
+std::mem::drop.
+std::boxed::Box.
+std::borrow::ToOwned.
+std::clone::Clone.
+std::cmp::{PartialEq, PartialOrd, Eq, Ord}.
+std::convert::{AsRef, AsMut, Into, From}.
+std::default::Default.
+std::iter::{Iterator, Extend, IntoIterator, DoubleEndedIterator, ExactSizeIterator}.
+std::option::Option::{self, Some, None}.
+std::result::Result::{self, Ok, Err}.
+std::string::{String, ToString}.
+std::vec::Vec.
+std::convert::{TryFrom, TryInto}.
+std::iter::FromIterator.
+
+#![allow(unused)] +fn main() { +use std::io::prelude::*; +}
Collection
+Vector
+Create and Insert:
++#![allow(unused)] +fn main() { +let mut v = Vec::new(); +v.push(1); +}
Access and Get:
++#![allow(unused)] +fn main() { +let v = vec![1, 2, 3, 4, 5]; + +let third: &i32 = &v[2]; +println!("3rd: {}", third); + +match v.get(2) { + Some(third) => println!("3rd: {}", third), + None => println!("None."), +} +}
Visit:
++#![allow(unused)] +fn main() { +let v = vec![1, 2, 3]; + +for i in &v { + println!("{}", i); +} +}
Visit and Mutate:
++#![allow(unused)] +fn main() { +let mut v = vec![1, 2, 3]; + +for i in &mut v { + *i += 10 +} +}
Store different types:
++enum IpAddr { + V4(String), + V6(String) +} + +fn main() { + let v = vec![ + IpAddr::V4("127.0.0.1".to_string()), + IpAddr::V6("::1".to_string()) + ]; + + for ip in v { + show_addr(ip) + } +} + +fn show_addr(ip: IpAddr) { + println!("{:?}",ip); +}
HashMap
++#![allow(unused)] +fn main() { +use std::collections::HashMap; +}
+#![allow(unused)] +fn main() { +// Create. +let mut scores = HashMap::new(); + +// Insert. +scores.insert(String::from("Blue"), 10); +scores.insert(String::from("Yellow"), 50); +scores.entry("Red").or_insert(5); + +// Get. +let team_name = String::from("Blue"); +let score: Option<&i32> = scores.get(&team_name); + +// Visit +for (key, value) in &scores { + println!("{}: {}", key, value); +} + +// Transform. +let from_list: HashMap<_,_> = some_list.into_iter().collect(); +}
HashSet
+-
+
- insert. +
- contains. +
- union. +
- difference. +
- intersection. +
- symmetric_difference. +
Error Handling
+Result Type
++use std::fs::File; +use std::io::ErrorKind; + +fn main() { + let f = File::open("hello.txt"); + + let f = match f { + Ok(file) => file, + Err(error) => match error.kind() { + ErrorKind::NotFound => match File::create("hello.txt") { + Ok(fc) => fc, + Err(e) => panic!("Problem creating the file: {:?}", e), + }, + other_error => panic!("Problem opening the file: {:?}", other_error), + }, + }; +}
Result Type Compositor
+-
+
or: logic or.
+and: logic and.
+or_else: logic or function.
+and_then: logic and function.
+filter:Optionfilter function.
+map:Ok/Somemap function.
+map_or:Ok/Somemap function with defaults value.
+map_or_else:Ok/Somemap function with defaults function.
+map_err:Errmap function.
+ok_or:Option->Resultwith error message.
+ok_or_else:Option->Resultwith error message function.
+
Error Handling Macro
+? for Result type:
+#![allow(unused)] +fn main() { +use std::fs::File; +use std::io; +use std::io::Read; + +fn open_file() -> Result<File, Box<dyn std::error::Error>> { + let mut f = File::open("hello.txt")?; + Ok(f) +} + +fn read_username_from_file() -> Result<String, io::Error> { + let mut s = String::new(); + File::open("hello.txt")?.read_to_string(&mut s)?; + Ok(s) +} +}
? for Option type:
+#![allow(unused)] +fn main() { +fn last_char_of_first_line(text: &str) -> Option<char> { + text.lines().next()?.chars().last() +} +}
Error Trait
+Standard Error Trait
++#![allow(unused)] +fn main() { +use std::fmt::{Debug, Display}; + +pub trait Error: Debug + Display { + fn source(&self) -> Option<&(Error + 'static)> { ... } +} +}
+use std::fs::read_to_string; +use std::error::Error; + +fn main() -> Result<(), Box<dyn Error>> { + let html = render()?; + println!("{}", html); + Ok(()) +} + +fn render() -> Result<String, Box<dyn Error>> { + let file = std::env::var("MARKDOWN")?; + let source = read_to_string(file)?; + Ok(source) +}
Custom Error Type
++use std::error; +use std::fmt; + +#[derive(Debug)] +struct AppError; + +impl fmt::Display for AppError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "An Error Occurred, Please Try Again!") + } +} + +impl error::Error for AppError { + fn description(&self) -> &str { + "Invalid App" + } + + fn source(&self) -> Option<&(dyn error::Error + 'static)> { + None + } + + fn cause(&self) -> Option<&dyn error::Error> { + None + } +} + +fn produce_error() -> Result<(), AppError> { + Err(AppError) +} + +fn main(){ + match produce_error() { + Err(e) => eprintln!("{}", e), + _ => println!("No error"), + } + + eprintln!("{:?}", produce_error()); // Err({ file: src/main.rs, line: 17 }) +}
Convert From Standard Error
++use std::fs::File; +use std::io::{self, Read}; +use std::num; + +#[derive(Debug)] +struct AppError { + kind: String, + message: String, +} + +impl From<io::Error> for AppError { + fn from(error: io::Error) -> Self { + AppError { + kind: String::from("io"), + message: error.to_string(), + } + } +} + +impl From<num::ParseIntError> for AppError { + fn from(error: num::ParseIntError) -> Self { + AppError { + kind: String::from("parse"), + message: error.to_string(), + } + } +} + +fn main() -> Result<(), AppError> { + let mut file = File::open("hello_world.txt")?; + + let mut content = String::new(); + file.read_to_string(&mut content)?; + + let _number: usize; + _number = content.parse()?; + + Ok(()) +} + + +// --------------- 上述代码运行后的可能输出 --------------- +// 01. 若 hello_world.txt 文件不存在 +// Error: AppError { kind: "io", message: "No such file or directory" } +// 02. 若用户没有相关的权限访问 hello_world.txt +// Error: AppError { kind: "io", message: "Permission denied" } +// 03. 若 hello_world.txt 包含有非数字的内容，例如 Hello, world! +// Error: AppError { kind: "parse", message: "invalid digit found in string" }
Format Print
+Format Print Macros
+-
+
print!.
+println!.
+eprint!.
+eprintln!.
+format!.
+
+#![allow(unused)] +fn main() { +println!("Hello"); // => "Hello" +println!("Hello, {}!", "world"); // => "Hello, world!" +println!("The number is {}", 1); // => "The number is 1" +println!("{:?}", (3, 4)); // => "(3, 4)" +println!("{value}", value=4); // => "4" +println!("{} {}", 1, 2); // => "1 2" +println!("{:04}", 42); // => "0042" with leading zeros +}
+fn main() { + let s = "hello"; + println!("{}, world", s); + let s1 = format!("{}, world", s); + print!("{}", s1); + print!("{}\n", "!"); +}
Format Print Placeholder
+-
+
{}.
+{:?}.
+{:#?}.
+- Index placeholder. +
- Alias placeholder. +
+fn main() { + println!("{1}{}{0}{}", 1, 2); // => 2112 + println!("{name} {}", 1, name = 2); // => "2 1" + println!("{a} {c} {b}", a = "a", b = 'b', c = 3); // => "a 3 b" +}
-
+
- Pad placeholder. +
+fn main() { + // 以下全部输出 "Hello x !" + // 为"x"后面填充空格, 补齐宽度5 + println!("Hello {:5}!", "x"); + // 使用参数5来指定宽度 + println!("Hello {:1$}!", "x", 5); + // 使用x作为占位符输出内容, 同时使用5作为宽度 + println!("Hello {1:0$}!", 5, "x"); + // 使用有名称的参数作为宽度 + println!("Hello {:width$}!", "x", width = 5); + + // 使用参数5为参数x指定宽度, 同时在结尾输出参数5 => Hello x !5 + println!("Hello {:1$}!{}", "x", 5); + + // 宽度是5 => Hello 5! + println!("Hello {:5}!", 5); + // 显式的输出正号 => Hello +5! + println!("Hello {:+}!", 5); + // 宽度5, 使用0进行填充 => Hello 00005! + println!("Hello {:05}!", 5); + // 负号也要占用一位宽度 => Hello -0005! + println!("Hello {:05}!", -5); +}
-
+
- Alignment placeholder. +
+fn main() { + // 以下全部都会补齐5个字符的长度 + // 左对齐 => Hello x ! + println!("Hello {:<5}!", "x"); + // 右对齐 => Hello x + println!("Hello {:>5}!", "x"); + // 居中对齐 => Hello x ! + println!("Hello {:^5}!", "x"); + + // 对齐并使用指定符号填充 => Hello x&&&&! + // 指定符号填充的前提条件是必须有对齐字符 + println!("Hello {:&<5}!", "x"); +}
-
+
- Precision placeholder. +
+fn main() { + let v = 3.1415926; + // 保留小数点后两位 => 3.14 + println!("{:.2}", v); + // 带符号保留小数点后两位 => +3.14 + println!("{:+.2}", v); + // 不带小数 => 3 + println!("{:.0}", v); + // 通过参数来设定精度 => 3.1416, 相当于{:.4} + println!("{:.1$}", v, 4); + + let s = "hello I'm some one"; + // 保留字符串前三个字符 => hel + println!("{:.3}", s); + // {:.*} 接收两个参数, 第一个是精度, 第二个是被格式化的值 => Hello abc! + println!("Hello {:.*}!", 3, "abcdefg"); +}
-
+
- Radix placeholder:
boxXeE. +-
+
fmt::Binarytrait.
+fmt::Octaltrait.
+fmt::LowerHextrait.
+fmt::UpperHextrait.
+fmt::LowerExptrait.
+fmt::UpperExptrait.
+
+
+fn main() { + // 二进制 => 0b11011! + println!("{:#b}!", 27); + // 八进制 => 0o33! + println!("{:#o}!", 27); + // 十进制 => 27! + println!("{}!", 27); + // 小写十六进制 => 0x1b! + println!("{:#x}!", 27); + // 大写十六进制 => 0x1B! + println!("{:#X}!", 27); + + // 不带前缀的十六进制 => 1b! + println!("{:x}!", 27); + + // 使用0填充二进制, 宽度为10 => 0b00011011! + println!("{:#010b}!", 27); + + println!("{:2e}", 1000000000); // => 1e9 + println!("{:2E}", 1000000000); // => 1E9 +}
Debug Trait
++#[derive(Debug)] +struct Person { + name: String, + age: u8 +} + +fn main() { + let i = 3.1415926; + let s = String::from("hello"); + let v = vec![1, 2, 3]; + let p = Person{name: "name".to_string(), age: 18}; + println!("{:?}, {:?}, {:?}, {:?}", i, s, v, p); +}
Display Trait
++use std::fmt; + +struct Person { + name: String, + age: u8, +} + +impl fmt::Display for Person { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!( + f, + "My name is {}, {} year old.", + self.name, self.age + ) + } +} + +fn main() { + let p = Person { + name: "name".to_string(), + age: 18, + }; + + println!("{}", p); +}
Lifetime
+显式地使用生命周期, 可以让编译器正确地认识到多个引用之间的关系.
++#![allow(unused)] +fn main() { +&i32 // 一个引用 +&'a i32 // 具有显式生命周期的引用 +&'a mut i32 // 具有显式生命周期的可变引用 +}
+#![allow(unused)] +fn main() { +struct ImportantExcerpt<'a> { + part: &'a str, +} + + +fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { + if x.len() > y.len() { + x + } else { + y + } +} +}
Function Lifetime
+函数或者方法中,
+参数的生命周期被称为输入生命周期,
+返回值的生命周期被称为输出生命周期:
-
+
- 每一个引用参数都会获得独自的生命周期:
+
fn foo<'a, 'b>(x: &'a i32, y: &'b i32).
+ - 若只有一个输入生命周期, 则该生命周期会被赋给所有输出生命周期. +
- 若存在多个输入生命周期, 且其中一个是
&self/&mut self, +则&self生命周期被赋给所有输出生命周期 (除非显式地声明输出生命周期).
+
Static Lifetime
+生命周期'static表示持续整个程序,
+例如字符串字面量和特征对象.
Lifetime Constraint
+-
+
'a: 'b:'a生命周期更长.
+T: 'a:T生命周期更长.
+
Closure
+Function Parameter Closure
+改变捕获变量的所有权 (FnOnce):
++fn fn_once<F>(func: F) +where + F: FnOnce(usize) -> bool + Copy, +{ + println!("{}", func(3)); + println!("{}", func(4)); +} + +fn main() { + let x = vec![1, 2, 3]; + fn_once(|z|{z == x.len()}) +}
可变借用捕获 (FnMut):
++fn main() { + let mut s = String::new(); + + let update_string = |str| s.push_str(str); + + exec(update_string); + + println!("{:?}",s); +} + +fn exec<'a, F: FnMut(&'a str)>(mut f: F) { + f("hello") +}
不可变借用捕获 (Fn):
++fn main() { + let s = "hello, ".to_string(); + + let update_string = |str| println!("{},{}",s,str); + + exec(update_string); + + println!("{:?}",s); +} + +fn exec<'a, F: Fn(String) -> ()>(f: F) { + f("world".to_string()) +}
-
+
- 所有闭包都自动实现了
FnOnce特征, 因此任何一个闭包都至少可以被调用一次.
+ - 没有移出所捕获变量的所有权的闭包自动实现了
FnMut特征.
+ - 不需要对捕获变量进行改变的闭包自动实现了
Fn特征.
+
Function Return Closure
++#![allow(unused)] +fn main() { +fn factory() -> impl Fn(i32) -> i32 { + let num = 5; + |x| x + num +} +}
+#![allow(unused)] +fn main() { +fn factory(x:i32) -> Box<dyn Fn(i32) -> i32> { + let num = 5; + + if x > 1{ + Box::new(move |x| x + num) + } else { + Box::new(move |x| x - num) + } +} +}
Iterator
++#![allow(unused)] +fn main() { +let arr = [1, 2, 3]; + +for v in arr.into_iter() { + println!("{}", v); +} +}
+fn main() { + let arr = [1, 2, 3]; + let mut arr_iter = arr.into_iter(); + + assert_eq!(arr_iter.next(), Some(1)); + assert_eq!(arr_iter.next(), Some(2)); + assert_eq!(arr_iter.next(), Some(3)); + assert_eq!(arr_iter.next(), None); +}
Iterator Trait
++#![allow(unused)] +fn main() { +pub trait Iterator { + type Item; + + fn next(&mut self) -> Option<Self::Item>; +} + +impl<I: Iterator> IntoIterator for I { + type Item = I::Item; + type IntoIter = I; + + #[inline] + fn into_iter(self) -> I { + self + } +} +}
-
+
iter: 不可变借用.
+iter_mut: 可变借用.
+into_iter: 改变所有权.
+
+#![allow(unused)] +fn main() { +fn iter(&self) -> Iter // Iter implements Iterator<Item = &U> +fn iter_mut(&mut self) -> IterMut // IterMut implements Iterator<Item = &mut U> +fn into_iter(self) -> IntoIter // IntoIter implements Iterator<Item = U> +}
+fn main() { + let values = vec![1, 2, 3]; + + for v in values.into_iter() { + println!("{}", v) + } + + // 下面的代码将报错. + // println!("{:?}",values); + + let values = vec![1, 2, 3]; + let _values_iter = values.iter(); + + // 不会报错. + println!("{:?}", values); + + let mut values = vec![1, 2, 3]; + // 对 values 中的元素进行可变借用. + let mut values_iter_mut = values.iter_mut(); + + // 取出第一个元素, 并修改为0. + if let Some(v) = values_iter_mut.next() { + *v = 0; + } + + // 输出 [0, 2, 3]. + println!("{:?}", values); +}
Implement iterator:
++struct Counter { + count: u32, +} + +impl Counter { + fn new() -> Counter { + Counter { count: 0 } + } +} + +impl Iterator for Counter { + type Item = u32; + + fn next(&mut self) -> Option<Self::Item> { + if self.count < 5 { + self.count += 1; + Some(self.count) + } else { + None + } + } +} + +fn main() { + let mut counter = Counter::new(); + assert_eq!(counter.next(), Some(1)); + assert_eq!(counter.next(), Some(2)); + assert_eq!(counter.next(), Some(3)); + assert_eq!(counter.next(), Some(4)); + assert_eq!(counter.next(), Some(5)); + assert_eq!(counter.next(), None); + + let sum: u32 = Counter::new() + .zip(Counter::new().skip(1)) + .map(|(a, b)| a * b) + .filter(|x| x % 3 == 0) + .sum(); + assert_eq!(18, sum); +}
Adapter Methods
+-
+
- 消费性适配器: 获取迭代器的所有权, 并消耗迭代器中所有元素.
+
-
+
collect::<T>().
+- fold. +
- partition. +
sum::<T>().
+
+ - 迭代性适配器: 惰性方法 (Lazy Iterator)
+
-
+
- enumerate. +
- filter. +
- filter_map. +
- map. +
- take_while. +
- zip. +
+ - Ordinary iterator methods:
+
-
+
- Iterator::any. +
- Iterator::find. +
+
More adapter methods see Iterator trait
+documentation.
+fn main() { + let v1 = vec![1, 2, 3]; + let v1_iter = v1.iter(); + let total: i32 = v1_iter.sum(); + assert_eq!(total, 6); + + // v1_iter 是借用了 v1, 因此 v1 可以照常使用. + println!("{:?}",v1); + + // 以下代码会报错, 因为 `sum` 拿到了迭代器 `v1_iter` 的所有权. + // println!("{:?}",v1_iter); +}
+fn main() { + let v1: Vec<i32> = vec![1, 2, 3]; + let v2: Vec<_> = v1.iter().map(|x| x + 1).collect(); + assert_eq!(v2, vec![2, 3, 4]); +}
+use std::collections::HashMap; + +fn main() { + let names = ["name1", "name2"]; + let ages = [18, 18]; + let folks: HashMap<_, _> = names.into_iter().zip(ages.into_iter()).collect(); + println!("{:?}",folks); +}
Smart Pointer
+Box Type
+Box<T> 将一个值分配到堆上, 然后在栈上保留一个智能指针指向堆上数据:
-
+
- 实现转移所有权时的零拷贝. +
- 将不定长类型转换为定长类型. +
+fn main() { + // 在栈上创建一个长度为 1000 的数组. + let arr = [0;1000]; + // 将 arr 所有权转移 arr1, 由于 `arr` 分配在栈上, 因此直接重新深拷贝了一份数据. + let arr1 = arr; + + // arr 和 arr1 都拥有各自的栈上数组, 因此不会报错. + println!("{:?}", arr.len()); + println!("{:?}", arr1.len()); + + // 在堆上创建一个长度为 1000 的数组, 然后使用一个智能指针指向它. + let arr = Box::new([0;1000]); + // 将堆上数组的所有权转移给 arr1, 由于数据在堆上, 因此仅仅拷贝了智能指针的结构体, 底层数据并没有被拷贝. + // 所有权顺利转移给 arr1, arr 不再拥有所有权. + let arr1 = arr; + println!("{:?}", arr1.len()); + // 由于 arr 不再拥有底层数组的所有权, 因此下面代码将报错. + // println!("{:?}", arr.len()); +}
+#![allow(unused)] +fn main() { +enum List { + Cons(i32, Box<List>), + Nil, +} +}
Deref Trait
+-
+
&smart_pointer+=>smart_pointer.defer().
+*smart_pointer+=>*(smart_pointer.defer()).
+smart_pointer.method()+=>(&smart_pointer).method()+=>(smart_pointer.defer()).method().
+- When
T: Deref<Target=U>, then&T => &U.
+ - When
T: DerefMut<Target=U>, then&mut T => &mut U.
+ - When
T: Deref<Target=U>, then&mut T => &U.
+
+use core::ops::{self}; +use crate::str::{self, from_boxed_utf8_unchecked}; +use crate::vec::Vec; + +struct String { + vec: Vec<u8>, +} + +impl ops::Deref for String { + type Target = str; + + fn deref(&self) -> &str { + unsafe { str::from_utf8_unchecked(&self.vec) } + } +} + +struct MyBox<T>(T); + +impl<T> MyBox<T> { + fn new(x: T) -> MyBox<T> { + MyBox(x) + } +} + +impl<T> ops::Deref for MyBox<T> { + type Target = T; + + fn deref(&self) -> &Self::Target { + &self.0 + } +} + +fn main() { + let x = MyBox::new(5); + assert_eq!(5, *x); + // => *(x.deref()) + // => *(&x.0) + // => x.0 + + let s = MyBox::new(String::from("hello world")); + display(&s); + // => &MyBox + // => MyBox.deref() + // => &String + // => String.deref() + // => &str + + let hello_world = MyBox::new(String::from("hello, world")); + let s1: &str = &hello_world; + // => &MyBox<String> + // => MyBox<String>.deref() + // => &String + // => String.deref() + // => &str + let s2: String = hello_world.to_string(); + // => MyBox<String>.to_string() + // => (&MyBox<String>).to_string() + // => (MyBox<String>.defer()).to_string() + // => (&String).to_string() + let ptr: *const u8 = hello_world.as_ptr(); + // => MyBox<String>.as_ptr() + // => (&MyBox<String>).as_ptr() + // => (MyBox<String>.defer()).as_ptr() + // => (&String).as_ptr() + // => (String.defer()).as_ptr() + // => (&str).as_ptr() +} + +fn display(s: &str) { + println!("{}", s); +}
Drop Trait
+Drop order:
+-
+
- 变量级别, 按照逆序的方式, 先创建的变量后 drop. +
- 结构体内部, 按照顺序的方式, 结构体中的字段按照定义中的顺序依次 drop. +
Reference Counting Type
+通过引用计数的方式, 允许一个数据资源在同一时刻拥有多个所有者.
++use std::rc::Rc; + +fn main() { + let a = Rc::new(String::from("hello, world")); + let b = Rc::clone(&a); // 复制了智能指针并增加了引用计数, 并没有克隆底层数据. + assert_eq!(2, Rc::strong_count(&a)); + assert_eq!(Rc::strong_count(&a), Rc::strong_count(&b)) +}
-
+
Rc/Arc是不可变引用, 无法修改它指向的值.
+Rc<T>是一个智能指针, 实现了Deref特征, 可以直接使用T.
+- 一旦最后一个拥有者消失, 则资源会自动被回收. +
Arc: Atomic reference counting.
+
+use std::sync::Arc; +use std::thread; + +fn main() { + let s = Arc::new(String::from("Multiple threads walker")); + + for _ in 0..10 { + let s = Arc::clone(&s); + let handle = thread::spawn(move || { + println!("{}", s) + }); + } +}
Cell and RefCell Type
+Cell for copyable type.
+use std::cell::Cell; + +fn main() { + let c = Cell::new("abc"); + let one = c.get(); + c.set("xyz"); + let two = c.get(); + println!("{}, {}", one, two); // abc, xyz +}
+#![allow(unused)] +fn main() { +use std::cell::Cell; + +fn retain_even(nums: &mut Vec<i32>) { + let slice: &[Cell<i32>] = Cell::from_mut(&mut nums[..]) + .as_slice_of_cells(); + + let mut i = 0; + + for num in slice.iter().filter(|num| is_even(num.get())) { + slice[i].set(num.get()); + i += 1; + } + + nums.truncate(i); +} +}
RefCell for borrowing reference:
-
+
- 实现内部可变性: 不可变值的可变借用.
+
imut_self.refcell_member.borrow_mut().changeMember().
+ Rc<RefCell<T>>: 实现多个可变数据所有者.
+- 实现编译期可变借用与不可变借用共存,
+但会引起运行时
panic.
+
+use std::cell::RefCell; + +fn main() { + let s = RefCell::new(String::from("hello, world")); + let s1 = s.borrow(); + let s2 = s.borrow_mut(); + + println!("{}, {}", s1, s2); +}
通过包裹一层 RefCell,
+将不可变借用 &self 的成员成为一个可变值,
+然后实现修改:
+use std::cell::RefCell; + +pub trait Messenger { + fn send(&self, msg: String); +} + +pub struct MsgQueue { + msg_cache: RefCell<Vec<String>>, +} + +impl Messenger for MsgQueue { + fn send(&self, msg: String) { + self.msg_cache.borrow_mut().push(msg) + } +} + +fn main() { + let mq = MsgQueue { + msg_cache: RefCell::new(Vec::new()), + }; + mq.send("hello, world".to_string()); +}
Circle Reference
+Weak 通过 use std::rc::Weak 引入, 具有以下特点:
-
+
- 可访问, 但没有所有权, 不增加引用计数, 不影响 drop. +
- 可由
Rc<T>调用downgrade方法转换成Weak<T>.
+ Weak<T>可使用upgrade方法转换成Option<Rc<T>>, +如果资源已经被释放, 则Option的值是None.
+- 常用于解决循环引用的问题. +
+use std::cell::RefCell; +use std::rc::{Rc, Weak}; + +#[derive(Debug)] +struct Node { + value: i32, + parent: RefCell<Weak<Node>>, + children: RefCell<Vec<Rc<Node>>>, +} + +fn main() { + let leaf = Rc::new(Node { + value: 3, + parent: RefCell::new(Weak::new()), + children: RefCell::new(vec![]), + }); + + println!( + "leaf strong = {}, weak = {}", + Rc::strong_count(&leaf), + Rc::weak_count(&leaf), + ); + + { + let branch = Rc::new(Node { + value: 5, + parent: RefCell::new(Weak::new()), + children: RefCell::new(vec![Rc::clone(&leaf)]), + }); + + *leaf.parent.borrow_mut() = Rc::downgrade(&branch); + + println!( + "branch strong = {}, weak = {}", + Rc::strong_count(&branch), + Rc::weak_count(&branch), + ); + + println!( + "leaf strong = {}, weak = {}", + Rc::strong_count(&leaf), + Rc::weak_count(&leaf), + ); + } + + println!("leaf parent = {:?}", leaf.parent.borrow().upgrade()); + println!( + "leaf strong = {}, weak = {}", + Rc::strong_count(&leaf), + Rc::weak_count(&leaf), + ); +}
Phantom Type
+虚类型/幽灵类型参数是一种在运行时不出现, +仅进行静态编译检查的类型参数.
++#![allow(unused)] +fn main() { +use std::marker::PhantomData; + +struct Iter<'a, T: 'a> { + ptr: *const T, + end: *const T, + _marker: PhantomData<&'a T>, +} + +struct Vec<T> { + data: *const T, + len: usize, + cap: usize, + _marker: PhantomData<T>, +} +}
+use std::marker::PhantomData; + +#[derive(PartialEq)] +struct PhantomTuple<A, B>(A, PhantomData<B>); + +#[derive(PartialEq)] +struct PhantomStruct<A, B> { first: A, phantom: PhantomData<B> } + +fn main() { + let _tuple1: PhantomTuple<char, f32> = PhantomTuple('Q', PhantomData); + let _tuple2: PhantomTuple<char, f64> = PhantomTuple('Q', PhantomData); + + let _struct1: PhantomStruct<char, f32> = PhantomStruct { + first: 'Q', + phantom: PhantomData, + }; + let _struct2: PhantomStruct<char, f64> = PhantomStruct { + first: 'Q', + phantom: PhantomData, + }; + + // 编译期错误！类型不匹配，所以这些值不能够比较： + println!("_tuple1 == _tuple2 yields: {}", + _tuple1 == _tuple2); + + // 编译期错误！类型不匹配，所以这些值不能够比较： + println!("_struct1 == _struct2 yields: {}", + _struct1 == _struct2); +}
+use std::ops::Add; +use std::marker::PhantomData; + +#[derive(Debug, Clone, Copy)] +enum Inch {} +#[derive(Debug, Clone, Copy)] +enum Mm {} + +#[derive(Debug, Clone, Copy)] +struct Length<Unit>(f64, PhantomData<Unit>); + +impl<Unit> Add for Length<Unit> { + type Output = Length<Unit>; + + fn add(self, rhs: Length<Unit>) -> Length<Unit> { + Length(self.0 + rhs.0, PhantomData) + } +} + +fn main() { + let one_foot: Length<Inch> = Length(12.0, PhantomData); + let one_meter: Length<Mm> = Length(1000.0, PhantomData); + + let two_feet = one_foot + one_foot; + let two_meters = one_meter + one_meter; + + println!("one foot + one_foot = {:?} in", two_feet.0); + println!("one meter + one_meter = {:?} mm", two_meters.0); + + // 编译期错误: 类型不匹配. + let compile_error = one_foot + one_meter; +}
Concurrent Programming
+Concurrency Programming Model
+| Name | Pros | Cons |
|---|---|---|
| OS Thread | simple, native model | consistent and context switch overhead |
| Event Driven | perf model | non-liner logic, callback hell |
| Coroutines | perf model | non-system abstraction |
| Actor | distributed model | complex flow control and retry logic |
| Async/Await | perf, native model | complex internal logic |
OS Threads for CPU intensive task (parallel computing),
+Async/Await for I/O intensive task (blocking I/O).
Threads
++use std::thread; +use std::time::Duration; + +fn main() { + let handle = thread::spawn(|| { + for i in 1..5 { + println!("hi number {} from the spawned thread!", i); + thread::sleep(Duration::from_millis(1)); + } + }); + + for i in 1..5 { + println!("hi number {} from the main thread!", i); + thread::sleep(Duration::from_millis(1)); + } + + handle.join().unwrap(); +}
Barrier
++use std::sync::{Arc, Barrier}; +use std::thread; + +fn main() { + let mut handles = Vec::with_capacity(6); + let barrier = Arc::new(Barrier::new(6)); + + for _ in 0..6 { + let b = barrier.clone(); + handles.push(thread::spawn(move|| { + println!("before wait"); + b.wait(); + println!("after wait"); + })); + } + + for handle in handles { + handle.join().unwrap(); + } +}
Condition Variables and Mutex
++use std::thread; +use std::sync::{Arc, Mutex, Condvar}; + +fn main() { + let pair = Arc::new((Mutex::new(false), Condvar::new())); + let pair2 = pair.clone(); + + thread::spawn(move|| { + let &(ref lock, ref cvar) = &*pair2; + let mut started = lock.lock().unwrap(); + println!("changing started"); + *started = true; + cvar.notify_one(); + }); + + let &(ref lock, ref cvar) = &*pair; + let mut started = lock.lock().unwrap(); + while !*started { + started = cvar.wait(started).unwrap(); + } + + println!("started changed"); +}
+use std::sync::{Arc, Mutex}; +use std::thread; + +fn main() { + let counter = Arc::new(Mutex::new(0)); + let mut handles = vec![]; + + for _ in 0..10 { + let counter = Arc::clone(&counter); + let handle = thread::spawn(move || { + let mut num = counter.lock().unwrap(); + *num += 1; + }); + handles.push(handle); + } + + for handle in handles { + handle.join().unwrap(); + } + + println!("Result: {}", *counter.lock().unwrap()); +}
Read and write mutex:
+-
+
- 同时允许多个读, 但最多只能有一个写. +
- 读和写不能同时存在. +
- 可以使用
read/try_read/write/try_write.
+
+use std::sync::RwLock; + +fn main() { + let lock = RwLock::new(5); + + // 同一时间允许多个读. + { + let r1 = lock.read().unwrap(); + let r2 = lock.read().unwrap(); + assert_eq!(*r1, 5); + assert_eq!(*r2, 5); + } // Drop. + + // 同一时间只允许一个写. + { + let mut w = lock.write().unwrap(); + *w += 1; + assert_eq!(*w, 6); + } // Drop. +}
Threads Communication
+Message channel:
++use std::sync::mpsc; +use std::thread; + +fn main() { + let (tx, rx) = mpsc::channel(); + + thread::spawn(move || { + tx.send(1).unwrap(); + }); + + // Block. + println!("receive {}", rx.recv().unwrap()); +}
Sync channel with message buffer:
++use std::sync::mpsc; +use std::thread; +use std::time::Duration; + +fn main() { + // Sync channel with 3 length buffer. + let (tx, rx)= mpsc::sync_channel(3); + + let handle = thread::spawn(move || { + println!("发送之前"); + tx.send(1).unwrap(); + println!("发送之后"); + }); + + println!("睡眠之前"); + thread::sleep(Duration::from_secs(3)); + println!("睡眠之后"); + + println!("receive {}", rx.recv().unwrap()); + handle.join().unwrap(); +}
Send message via for loop:
+use std::sync::mpsc; +use std::thread; +use std::time::Duration; + +fn main() { + let (tx, rx) = mpsc::channel(); + + thread::spawn(move || { + let values = vec![ + String::from("hi"), + String::from("from"), + String::from("the"), + String::from("thread"), + ]; + + for value in values { + tx.send(value).unwrap(); + thread::sleep(Duration::from_secs(1)); + } + }); + + for received in rx { + println!("Got: {}", received); + } +}
Multiple producers:
++use std::sync::mpsc; +use std::thread; + +fn main() { + let (tx, rx) = mpsc::channel(); + let tx1 = tx.clone(); + + thread::spawn(move || { + tx.send(String::from("hi from raw tx")).unwrap(); + }); + + thread::spawn(move || { + tx1.send(String::from("hi from cloned tx")).unwrap(); + }); + + for received in rx { + println!("Got: {}", received); + } +}
Multiple type message:
++use std::sync::mpsc::{self, Receiver, Sender}; + +enum Fruit { + Apple(u8), + Orange(String) +} + +fn main() { + let (tx, rx): (Sender<Fruit>, Receiver<Fruit>) = mpsc::channel(); + + tx.send(Fruit::Orange("sweet".to_string())).unwrap(); + tx.send(Fruit::Apple(2)).unwrap(); + + for _ in 0..2 { + match rx.recv().unwrap() { + Fruit::Apple(count) => println!("received {} apples", count), + Fruit::Orange(flavor) => println!("received {} oranges", flavor), + } + } +}
Tokio Semaphore
++use std::sync::Arc; +use tokio::sync::Semaphore; + +#[tokio::main] +async fn main() { + let semaphore = Arc::new(Semaphore::new(3)); + let mut join_handles = Vec::new(); + + for _ in 0..5 { + let permit = semaphore.clone().acquire_owned().await.unwrap(); + join_handles.push(tokio::spawn(async move { + /** + * Task here ... + */ + drop(permit); + })); + } + + for handle in join_handles { + handle.await.unwrap(); + } +}
Atomic Primitives
++use std::ops::Sub; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::thread::{self, JoinHandle}; +use std::time::Instant; + +const N_TIMES: u64 = 10000000; +const N_THREADS: usize = 10; + +static R: AtomicU64 = AtomicU64::new(0); + +fn add_n_times(n: u64) -> JoinHandle<()> { + thread::spawn(move || { + for _ in 0..n { + R.fetch_add(1, Ordering::Relaxed); + } + }) +} + +fn main() { + let s = Instant::now(); + let mut threads = Vec::with_capacity(N_THREADS); + + for _ in 0..N_THREADS { + threads.push(add_n_times(N_TIMES)); + } + + for thread in threads { + thread.join().unwrap(); + } + + assert_eq!(N_TIMES * N_THREADS as u64, R.load(Ordering::Relaxed)); + + println!("{:?}",Instant::now().sub(s)); +}
Ordering 内存顺序:
-
+
- Relaxed: 乱序. +
- Release: 设置内存屏障, 保证它之前的操作永远在它之前. +
- Acquire: 设置内存屏障, 保证它之后的操作永远在它之后. +
- AcqRel: Acquire + Release. +
- SeqCst: 顺序一致性. +
+use std::thread::{self, JoinHandle}; +use std::sync::atomic::{Ordering, AtomicBool}; + +static mut DATA: u64 = 0; +static READY: AtomicBool = AtomicBool::new(false); + +fn reset() { + unsafe { + DATA = 0; + } + READY.store(false, Ordering::Relaxed); +} + +fn producer() -> JoinHandle<()> { + thread::spawn(move || { + unsafe { + DATA = 100; // A + } + READY.store(true, Ordering::Release); // B: 内存屏障 ↑ + }) +} + +fn consumer() -> JoinHandle<()> { + thread::spawn(move || { + while !READY.load(Ordering::Acquire) {} // C: 内存屏障 ↓ + + assert_eq!(100, unsafe { DATA }); // D + }) +} + + +fn main() { + loop { + reset(); + + let t_producer = producer(); + let t_consumer = consumer(); + + t_producer.join().unwrap(); + t_consumer.join().unwrap(); + } +}
Spinlock:
++use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::{hint, thread}; + +fn main() { + let spinlock = Arc::new(AtomicUsize::new(1)); + let spinlock_clone = Arc::clone(&spinlock); + let thread = thread::spawn(move|| { + spinlock_clone.store(0, Ordering::SeqCst); + }); + + // 等待其它线程释放锁. + while spinlock.load(Ordering::SeqCst) != 0 { + hint::spin_loop(); + } + + if let Err(panic) = thread.join() { + println!("Thread had an error: {:?}", panic); + } +}
Send and Sync Trait
+Send and Sync:
+-
+
- Marker trait. +
- 实现
Send的类型可以在线程间安全的传递其所有权, +实现Sync的类型可以在线程间安全的共享 (通过引用). +若&T: Send, 则T: Sync.
+ - 绝大部分类型都实现了
Send/Sync, +例外: 原生指针,Cell/RefCell,Rc.
+
Thread Pool
++#![allow(unused)] +fn main() { +use std::sync::mpsc; +use std::sync::Arc; +use std::sync::Mutex; +use std::thread; + +type Job = Box<dyn FnOnce() + Send + 'static>; + +enum Message { + NewJob(Job), + Terminate, +} + +pub struct ThreadPool { + workers: Vec<Worker>, + sender: mpsc::Sender<Message>, +} + + +impl ThreadPool { + /// Create a new ThreadPool. + /// + /// The size is the number of threads in the pool. + /// + /// # Panics + /// + /// The `new` function will panic if the size is zero. + pub fn new(size: usize) -> ThreadPool { + assert!(size > 0); + + let (sender, receiver) = mpsc::channel(); + let receiver = Arc::new(Mutex::new(receiver)); + let mut workers = Vec::with_capacity(size); + + for id in 0..size { + workers.push(Worker::new(id, Arc::clone(&receiver))); + } + + ThreadPool { workers, sender } + } + + pub fn execute<F>(&self, f: F) + where + F: FnOnce() + Send + 'static, + { + let job = Box::new(f); + self.sender.send(Message::NewJob(job)).unwrap(); + } +} + +impl Drop for ThreadPool { + fn drop(&mut self) { + println!("Sending terminate message to all workers."); + + for _ in &self.workers { + self.sender.send(Message::Terminate).unwrap(); + } + + println!("Shutting down all workers."); + + for worker in &mut self.workers { + println!("Shutting down worker {}", worker.id); + + if let Some(thread) = worker.thread.take() { + thread.join().unwrap(); + } + } + } +} + +struct Worker { + id: usize, + thread: Option<thread::JoinHandle<()>>, +} + +impl Worker { + fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Message>>>) -> Worker { + let thread = thread::spawn(move || loop { + let message = receiver.lock().unwrap().recv().unwrap(); + + match message { + Message::NewJob(job) => { + println!("Worker {} got a job; executing.", id); + job(); + } + Message::Terminate => { + println!("Worker {} was told to terminate.", id); + break; + } + } + }); + + Worker { + id, + thread: Some(thread), + } + } +} +}
Asynchronous Programming
+Async and Await
+-
+
- 在
.await执行期间, 任务可能会在线程间转移.
+ .await只能用于 async fn 函数中.
+
+use futures::executor::block_on; +use futures::join; + +async fn learn_song() -> Song { /* ... */ } +async fn sing_song(song: Song) { /* ... */ } +async fn dance() { /* ... */ } + +async fn learn_and_sing() { + let song = learn_song().await; + sing_song(song).await; +} + +async fn async_main() { + let f1 = learn_and_sing(); + let f2 = dance(); + join!(f1, f2); +} + +fn main() { + block_on(async_main()); +}
+use futures::future; +use futures::select; + +pub fn main() { + let mut a_fut = future::ready(4); + let mut b_fut = future::ready(6); + let mut total = 0; + + loop { + select! { + a = a_fut => total += a, + b = b_fut => total += b, + complete => break, + default => panic!(), // 该分支永远不会运行. + }; + } + + assert_eq!(total, 10); +}
Future Trait
+-
+
Future代表一组计算, 惰性求值. 当.await调用时才真正开始执行.
+Future启动后会因资源等原因阻塞, 转入pending状态.
+Future阻塞后, 当资源准备好可以重新启动时, 会通过Waker.wake通知执行器, 等待被下一次poll.
+
+#![allow(unused)] +fn main() { +trait Future { + type Output; + fn poll( + self: Pin<&mut Self>, + cx: &mut Context<'_>, + ) -> Poll<Self::Output>; +} +}
+#![allow(unused)] + +fn main() { +use std::{ + future::Future, + pin::Pin, + sync::{Arc, Mutex}, + task::{Context, Poll, Waker}, + thread, + time::Duration, +}; + +pub struct TimerFuture { + shared_state: Arc<Mutex<SharedState>>, +} + +struct SharedState { + completed: bool, + waker: Option<Waker>, +} + +impl Future for TimerFuture { + type Output = (); + fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { + let mut shared_state = self.shared_state.lock().unwrap(); + + if shared_state.completed { + Poll::Ready(()) + } else { + shared_state.waker = Some(cx.waker().clone()); + Poll::Pending + } + } +} + +impl TimerFuture { + pub fn new(duration: Duration) -> Self { + let shared_state = Arc::new(Mutex::new(SharedState { + completed: false, + waker: None, + })); + + let thread_shared_state = shared_state.clone(); + + thread::spawn(move || { + thread::sleep(duration); + let mut shared_state = thread_shared_state.lock().unwrap(); + shared_state.completed = true; + if let Some(waker) = shared_state.waker.take() { + waker.wake() + } + }); + + TimerFuture { shared_state } + } +} +}
当 Future 会返回 Poll::Pending 时,
+一定要确保 wake 能被正常调用,
+否则会导致任务永远被挂起,
+再也不会被执行器 poll.
+use std::future::Future; +use std::pin::Pin; +use std::task::{Context, Poll}; +use std::time::{Duration, Instant}; + +struct Delay { + when: Instant, +} + +impl Future for Delay { + type Output = &'static str; + + fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) + -> Poll<&'static str> + { + if Instant::now() >= self.when { + println!("Hello world"); + Poll::Ready("done") + } else { + let waker = cx.waker().clone(); + let when = self.when; + + thread::spawn(move || { + let now = Instant::now(); + + if now < when { + thread::sleep(when - now); + } + + waker.wake(); + }); + + Poll::Pending + } + } +} + +#[tokio::main] +async fn main() { + let when = Instant::now() + Duration::from_millis(10); + let future = Delay { when }; + + let out = future.await; + assert_eq!(out, "done"); +}
Asynchronous Runtime
++use { + futures::{ + future::{BoxFuture, FutureExt}, + task::{waker_ref, ArcWake}, + }, + std::{ + future::Future, + sync::mpsc::{sync_channel, Receiver, SyncSender}, + sync::{Arc, Mutex}, + task::{Context, Poll}, + time::Duration, + }, + // 引入之前实现的定时器模块 + timer_future::TimerFuture, +}; + +struct Task { + future: Mutex<Option<BoxFuture<'static, ()>>>, + task_sender: SyncSender<Arc<Task>>, +} + +impl ArcWake for Task { + fn wake_by_ref(arc_self: &Arc<Self>) { + let cloned = arc_self.clone(); + arc_self + .task_sender + .send(cloned) + .expect("任务队列已满"); + } +} + +#[derive(Clone)] +struct Spawner { + task_sender: SyncSender<Arc<Task>>, +} + +impl Spawner { + fn spawn(&self, future: impl Future<Output = ()> + 'static + Send) { + let future = future.boxed(); + let task = Arc::new(Task { + future: Mutex::new(Some(future)), + task_sender: self.task_sender.clone(), + }); + self.task_sender.send(task).expect("任务队列已满"); + } +} + +struct Executor { + ready_queue: Receiver<Arc<Task>>, +} + +impl Executor { + fn run(&self) { + while let Ok(task) = self.ready_queue.recv() { + let mut future_slot = task.future.lock().unwrap(); + + if let Some(mut future) = future_slot.take() { + let waker = waker_ref(&task); + let context = &mut Context::from_waker(&*waker); + + if future.as_mut().poll(context).is_pending() { + // Future 未执行完，, 将它放回任务中, 等待下次被 poll. + *future_slot = Some(future); + } + } + } + } +} + +fn new_executor_and_spawner() -> (Executor, Spawner) { + const MAX_QUEUED_TASKS: usize = 10_000; + let (task_sender, ready_queue) = sync_channel(MAX_QUEUED_TASKS); + (Executor { ready_queue }, Spawner { task_sender }) +} + +fn main() { + let (executor, spawner) = new_executor_and_spawner(); + + spawner.spawn(async { + println!("howdy!"); + TimerFuture::new(Duration::new(2, 0)).await; + println!("done!"); + }); + + drop(spawner); + + // 运行执行器直到任务队列为空. + // 任务运行后, 会先打印 `howdy!`, 暂停 2 秒, 接着打印 `done!`. + executor.run(); +}
+use std::cell::RefCell; +use std::future::Future; +use std::pin::Pin; +use std::sync::{Arc, Mutex}; +use std::task::{Context, Poll, Waker}; +use std::thread; +use std::time::{Duration, Instant}; +use futures::task::{self, ArcWake}; +use crossbeam::channel; + +fn main() { + let mini_tokio = MiniTokio::new(); + + mini_tokio.spawn(async { + spawn(async { + delay(Duration::from_millis(100)).await; + println!("world"); + }); + + spawn(async { + println!("hello"); + }); + + delay(Duration::from_millis(200)).await; + std::process::exit(0); + }); + + mini_tokio.run(); +} + +struct MiniTokio { + scheduled: channel::Receiver<Arc<Task>>, + sender: channel::Sender<Arc<Task>>, +} + +impl MiniTokio { + fn new() -> MiniTokio { + let (sender, scheduled) = channel::unbounded(); + + MiniTokio { scheduled, sender } + } + + fn spawn<F>(&self, future: F) + where + F: Future<Output = ()> + Send + 'static, + { + Task::spawn(future, &self.sender); + } + + fn run(&self) { + CURRENT.with(|cell| { + *cell.borrow_mut() = Some(self.sender.clone()); + }); + + while let Ok(task) = self.scheduled.recv() { + task.poll(); + } + } +} + +pub fn spawn<F>(future: F) +where + F: Future<Output = ()> + Send + 'static, +{ + CURRENT.with(|cell| { + let borrow = cell.borrow(); + let sender = borrow.as_ref().unwrap(); + Task::spawn(future, sender); + }); +} + +async fn delay(dur: Duration) { + struct Delay { + when: Instant, + waker: Option<Arc<Mutex<Waker>>>, + } + + impl Future for Delay { + type Output = (); + + fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> { + if let Some(waker) = &self.waker { + let mut waker = waker.lock().unwrap(); + + if !waker.will_wake(cx.waker()) { + *waker = cx.waker().clone(); + } + } else { + let when = self.when; + let waker = Arc::new(Mutex::new(cx.waker().clone())); + self.waker = Some(waker.clone()); + + thread::spawn(move || { + let now = Instant::now(); + + if now < when { + thread::sleep(when - now); + } + + let waker = waker.lock().unwrap(); + waker.wake_by_ref(); + }); + } + + if Instant::now() >= self.when { + Poll::Ready(()) + } else { + Poll::Pending + } + } + } + + let future = Delay { + when: Instant::now() + dur, + waker: None, + }; + + future.await; +} + +thread_local! { + static CURRENT: RefCell<Option<channel::Sender<Arc<Task>>>> = + RefCell::new(None); +} + +struct Task { + future: Mutex<Pin<Box<dyn Future<Output = ()> + Send>>>, + executor: channel::Sender<Arc<Task>>, +} + +impl Task { + fn spawn<F>(future: F, sender: &channel::Sender<Arc<Task>>) + where + F: Future<Output = ()> + Send + 'static, + { + let task = Arc::new(Task { + future: Mutex::new(Box::pin(future)), + executor: sender.clone(), + }); + + let _ = sender.send(task); + } + + fn poll(self: Arc<Self>) { + let waker = task::waker(self.clone()); + let mut cx = Context::from_waker(&waker); + let mut future = self.future.try_lock().unwrap(); + let _ = future.as_mut().poll(&mut cx); + } +} + +impl ArcWake for Task { + fn wake_by_ref(arc_self: &Arc<Self>) { + let _ = arc_self.executor.send(arc_self.clone()); + } +}
+#[tokio::main] +async fn main() { + println!("Hello world"); +} + +fn main() { + tokio::runtime::Builder::new_multi_thread() + .enable_all() + .build() + .unwrap() + .block_on(async { + println!("Hello world"); + }) +}
Tests
++#![allow(unused)] +fn main() { +fn greeting(name: &str) -> String { + format!("Hello {}!", name) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + #[ignore] + #[should_panic] + #[should_panic(expected = "Panic message.")] + fn greeting_contains_name() { + let target = "name"; + let result = greeting("Name"); + assert!( + result.contains(target), + "Expect: `{}`, Result: `{}`", + target, + result + ); + } +} +}
IO
+Path
++use std::path::Path; + +fn main() { + let path = Path::new("."); + let new_path = path.join("a").join("b"); + + // 将路径转换成一个字符串切片 + match new_path.to_str() { + None => panic!("new path is not a valid UTF-8 sequence"), + Some(s) => println!("new path is {}", s), + } + + // `display` 方法返回一个可显示的结构体 + let display = path.display(); +}
Files
+-
+
File::open.
+File::create.
+file.read_to_string.
+file.write_all.
+bufReader.lines.
+OpenOptions.
+fs::read_dir.
+fs::create_dir.
+fs::create_dir_all.
+fs::remove_file.
+fs::remove_dir.
+fs::symlink.
+
+use std::error::Error; +use std::fs::File; +use std::io::prelude::*; +use std::path::Path; + +fn main() { + let path = Path::new("hello.txt"); + let display = path.display(); + + let mut file = match File::open(&path) { + Err(why) => panic!("couldn't open {}: {}", display, + why.description()), + Ok(file) => file, + }; + + let mut s = String::new(); + match file.read_to_string(&mut s) { + Err(why) => panic!("couldn't read {}: {}", display, + why.description()), + Ok(_) => print!("{} contains:\n{}", display, s), + } +}
+use std::fs::File; +use std::io::{self, BufRead}; +use std::path::Path; + +fn main() { + if let Ok(lines) = read_lines("./hosts") { + for line in lines { + if let Ok(ip) = line { + println!("{}", ip); + } + } + } +} + +fn read_lines<P>(filename: P) -> io::Result<io::Lines<io::BufReader<File>>> +where P: AsRef<Path>, { + let file = File::open(filename)?; + Ok(io::BufReader::new(file).lines()) +}
+static LOREM_IPSUM: &'static str = "Words"; + +use std::error::Error; +use std::fs::File; +use std::io::prelude::*; +use std::path::Path; + +fn main() { + let path = Path::new("out/lorem_ipsum.txt"); + let display = path.display(); + + let mut file = match File::create(&path) { + Err(why) => panic!("couldn't create {}: {}", + display, + why.description()), + Ok(file) => file, + }; + + match file.write_all(LOREM_IPSUM.as_bytes()) { + Err(why) => { + panic!("couldn't write to {}: {}", display, + why.description()) + }, + Ok(_) => println!("successfully wrote to {}", display), + } +}
+use std::fs; +use std::fs::{File, OpenOptions}; +use std::io; +use std::io::prelude::*; +use std::os::unix; +use std::path::Path; + +fn cat(path: &Path) -> io::Result<String> { + let mut f = File::open(path)?; + let mut s = String::new(); + match f.read_to_string(&mut s) { + Ok(_) => Ok(s), + Err(e) => Err(e), + } +} + +fn echo(s: &str, path: &Path) -> io::Result<()> { + let mut f = File::create(path)?; + f.write_all(s.as_bytes()) +} + +fn touch(path: &Path) -> io::Result<()> { + match OpenOptions::new().create(true).write(true).open(path) { + Ok(_) => Ok(()), + Err(e) => Err(e), + } +} + +fn main() { + println!("`mkdir a`"); + match fs::create_dir("a") { + Err(why) => println!("! {:?}", why.kind()), + Ok(_) => {}, + } + + println!("`echo hello > a/b.txt`"); + echo("hello", &Path::new("a/b.txt")).unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + + println!("`mkdir -p a/c/d`"); + fs::create_dir_all("a/c/d").unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + + println!("`touch a/c/e.txt`"); + touch(&Path::new("a/c/e.txt")).unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + + println!("`ln -s ../b.txt a/c/b.txt`"); + if cfg!(target_family = "unix") { + unix::fs::symlink("../b.txt", "a/c/b.txt").unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + } + + println!("`cat a/c/b.txt`"); + match cat(&Path::new("a/c/b.txt")) { + Err(why) => println!("! {:?}", why.kind()), + Ok(s) => println!("> {}", s), + } + + println!("`ls a`"); + match fs::read_dir("a") { + Err(why) => println!("! {:?}", why.kind()), + Ok(paths) => for path in paths { + println!("> {:?}", path.unwrap().path()); + }, + } + + println!("`rm a/c/e.txt`"); + fs::remove_file("a/c/e.txt").unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + + println!("`rmdir a/c/d`"); + fs::remove_dir("a/c/d").unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); +}
System
+Process
++use std::process::Command; + +fn main() { + let output = Command::new("rustc") + .arg("--version") + .output().unwrap_or_else(|e| { + panic!("failed to execute process: {}", e) + }); + + if output.status.success() { + let s = String::from_utf8_lossy(&output.stdout); + print!("rustc succeeded and stdout was:\n{}", s); + } else { + let s = String::from_utf8_lossy(&output.stderr); + print!("rustc failed and stderr was:\n{}", s); + } +}
+use std::error::Error; +use std::io::prelude::*; +use std::process::{Command, Stdio}; + +static PROGRAM: &'static str = +"the quick brown fox jumped over the lazy dog\n"; + +fn main() { + let process = match Command::new("wc") + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .spawn() { + Err(why) => panic!("couldn't spawn wc: {}", why.description()), + Ok(process) => process, + }; + + match process.stdin.unwrap().write_all(PROGRAM.as_bytes()) { + Err(why) => panic!("couldn't write to wc stdin: {}", + why.description()), + Ok(_) => println!("sent program to wc"), + } + + let mut s = String::new(); + match process.stdout.unwrap().read_to_string(&mut s) { + Err(why) => panic!("couldn't read wc stdout: {}", + why.description()), + Ok(_) => print!("wc responded with:\n{}", s), + } +}
Command Line
+++use std::env; +use std::error::Error; +use std::fs; +use std::process; + +pub struct Config { + pub query: String, + pub filename: String, + pub case_sensitive: bool, +} + +impl Config { + pub fn new(args: &[String]) -> Result<Config, &'static str> { + if args.len() < 3 { + return Err("not enough arguments"); + } + + let query = args[1].clone(); + let filename = args[2].clone(); + + let case_sensitive = env::var("CASE_INSENSITIVE").is_err(); + + Ok(Config { + query, + filename, + case_sensitive, + }) + } +} + +pub fn run(config: Config) -> Result<(), Box<dyn Error>> { + let contents = fs::read_to_string(config.filename)?; + + let results = if config.case_sensitive { + search(&config.query, &contents) + } else { + search_case_insensitive(&config.query, &contents) + }; + + for line in results { + println!("{}", line); + } + + Ok(()) +} + +pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { + let mut results = Vec::new(); + + for line in contents.lines() { + if line.contains(query) { + results.push(line); + } + } + + results +} + +pub fn search_case_insensitive<'a>( + query: &str, + contents: &'a str, +) -> Vec<&'a str> { + let query = query.to_lowercase(); + let mut results = Vec::new(); + + for line in contents.lines() { + if line.to_lowercase().contains(&query) { + results.push(line); + } + } + + results +} + +fn main() { + let args: Vec<String> = env::args().collect(); + + let config = Config::new(&args).unwrap_or_else(|err| { + eprintln!("Problem parsing arguments: {}", err); + process::exit(1); + }); + + if let Err(e) = run(config) { + eprintln!("Application error: {}", e); + + process::exit(1); + } +}
Macros
++#![allow(unused)] +fn main() { +#[macro_export] +macro_rules! vec { + ( $( $x:expr ),* ) => { + { + let mut temp_vec = Vec::new(); + $( + temp_vec.push($x); + )* + temp_vec + } + }; +} +}
Unsafe Code
+unsafe {}:
-
+
- 对原始指针进行解引用. +
- 调用
不安全的函数 (包括 C 函数, 编译器内建指令, 原始分配器).
+ - 实现
不安全的特性.
+ - 访问
union字段.
+ - 改变静态数据. +
Comments
++#![allow(unused)] +fn main() { +// Line Comments +/* Block Comments */ +/// Document Line Comments +/** Document Block Comments */ +//! Crate Line Comments +/*! Crate Block Comments */ + +/// [`Option`] +/// [`Type`](struct@Type) +/// [`Type`](fn@Type) + +#[doc(alias = "alias" )] +}
Attributes
+-
+
- Crate scope:
#![crate_attribute].
+ - Module/Function scope:
#[item_attribute].
+
+#![allow(unused)] +fn main() { +#[attribute = "value"] +#[attribute(key = "value")] +#[attribute(value)] +}
Crate Attributes
++#![allow(unused)] +#![crate_type = "lib"] +#![crate_name = "rand"] +fn main() { +}
Linter Attributes
++#![allow(unused)] +fn main() { +#[allow(dead_code)] +#[allow(unused)] +}
Compile Attributes
++#[cfg(target_os = "linux")] +fn are_you_on_linux() { + println!("You are running linux!") +} + +#[cfg(not(target_os = "linux"))] +fn are_you_on_linux() { + println!("You are *not* running linux!") +} + +fn main() { + are_you_on_linux(); + + if cfg!(target_os = "linux") { + println!("Yes. It's definitely linux!"); + } else { + println!("Yes. It's definitely *not* linux!"); + } +}
Standard Library
+-
+
as_:borrowed->borrowed.
+into_:owned->owned(移除所有权).
+to_: +borrowed->borrowed, +borrowed->ownedon non-copy types, +owned->ownedon copy types.
+try_: 尝试一次, 失败则返回或报错.
+_mut: 可变借用.
+
Web Development
+Node.js Bindings
+Tasks suite for native Node.js add-ons:
-
+
- Computing intensive tasks with simple I/O:
+e.g
@node-rs/crc32(CPU SIMD instruction),@node-rs/bcrypt,@node-rs/jieba.
+ - System call tasks: +SIMD instruction, GPU instruction. +
Napi:
+Framework for building compiled Node.js add-ons in Rust via Node API.
+#![allow(unused)] +fn main() { +#[macro_use] +extern crate napi; + +/// import the preludes +use napi::bindgen_prelude::*; + +/// module registration is done by the runtime, no need to explicitly do it now. +#[napi] +fn fibonacci(n: u32) -> u32 { + match n { + 1 | 2 => 1, + _ => fibonacci(n - 1) + fibonacci(n - 2), + } +} + +/// use `Fn`, `FnMut` or `FnOnce` traits to defined JavaScript callbacks +/// the return type of callbacks can only be `Result`. +#[napi] +fn get_cwd<T: Fn(String) -> Result<()>>(callback: T) { + callback(env::current_dir().unwrap().to_string_lossy().to_string()).unwrap(); +} + +/// or, define the callback signature in where clause +#[napi] +fn test_callback<T>(callback: T) +where T: Fn(String) -> Result<()> +{} + +/// async fn, require `async` feature enabled. +/// [dependencies] +/// napi = {version="2", features=["async"]} +#[napi] +async fn read_file_async(path: String) -> Result<Buffer> { + tokio::fs::read(path) + .map(|r| match r { + Ok(content) => Ok(content.into()), + Err(e) => Err(Error::new( + Status::GenericFailure, + format!("failed to read file, {}", e), + )), + }) + .await +} +}
Neon:
+Rust bindings for safe and fast native Node.js modules.
+use neon::context::{Context, ModuleContext, FunctionContext}; +use neon::types::JsNumber; +use neon::result::JsResult; +use neon::result::NeonResult; + +fn fibonacci(n: i32) -> i32 { + return match n { + n if n < 1 => 0, + n if n <= 2 => 1, + _ => fibonacci(n - 1) + fibonacci(n - 2) + } +} + +fn fibonacci_api(mut cx: FunctionContext) -> JsResult<JsNumber> { + let handle = cx.argument::<JsNumber>(0).unwrap(); + let res = fibonacci(handle.value(&mut cx) as i32); + Ok(cx.number(res)) +} + +#[neon::main] +fn main(mut cx: ModuleContext) -> NeonResult<()> { + cx.export_function("fibonacci_rs", fibonacci_api)?; + Ok(()) +}
const { fibonacci_rs } = require('./index.node');
+
+const value = process.argv[2] || null;
+const number = parseInt(value);
+
+if (isNaN(number)) {
+ console.log('Provided value is not a number');
+ return;
+}
+
+const result = fibonacci_rs(number);
+console.log(result);
+Library
+-
+
- Num: Numeric Types and Traits +
- Rand: Random Number Generator +
- Regex: Regular Expression Engine +
- Chrono: DateTime Library +
- AsyncStd: Asynchronous Version Standard Library +
- Crossbeam: Concurrent Programming Tools +
- Tokio: Asynchronous Runtime +
- Rayon: Data Parallelism Library +
- Log: Logging Library +
- Tracing: Tracing Library +
- Serde: Serialization Framework +
- Axum: Tokio Web Framework +
- Rocket: Web Framework +
- Actix: Web Framework +
- Warp: Web Framework +
- Request: HTTP Client +
- Quiche: QUIC and HTTP/3 Library +
- Tonic: gPRC Framework +
- QuickWit: Distributed Search Engine +
- MeiliSearch: Realtime Search Engine +
- Clap: CLI Framework +
- Console: ProgressBar +
- Syn: Source Code Parser +
- Napi: Node.js Bindings Library: +
- Neon: Node.js Bindings Library: +
- Git: Git Bindings Library +
- PrettyAssertions +
- Criterion: Benchmarking Library +
- Clog: Conventional Changelog +
Reference
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/searcher.js b/searcher.js
new file mode 100644
index 00000000..dc03e0a0
--- /dev/null
+++ b/searcher.js
@@ -0,0 +1,483 @@
+"use strict";
+window.search = window.search || {};
+(function search(search) {
+ // Search functionality
+ //
+ // You can use !hasFocus() to prevent keyhandling in your key
+ // event handlers while the user is typing their search.
+
+ if (!Mark || !elasticlunr) {
+ return;
+ }
+
+ //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+ if (!String.prototype.startsWith) {
+ String.prototype.startsWith = function(search, pos) {
+ return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
+ };
+ }
+
+ var search_wrap = document.getElementById('search-wrapper'),
+ searchbar = document.getElementById('searchbar'),
+ searchbar_outer = document.getElementById('searchbar-outer'),
+ searchresults = document.getElementById('searchresults'),
+ searchresults_outer = document.getElementById('searchresults-outer'),
+ searchresults_header = document.getElementById('searchresults-header'),
+ searchicon = document.getElementById('search-toggle'),
+ content = document.getElementById('content'),
+
+ searchindex = null,
+ doc_urls = [],
+ results_options = {
+ teaser_word_count: 30,
+ limit_results: 30,
+ },
+ search_options = {
+ bool: "AND",
+ expand: true,
+ fields: {
+ title: {boost: 1},
+ body: {boost: 1},
+ breadcrumbs: {boost: 0}
+ }
+ },
+ mark_exclude = [],
+ marker = new Mark(content),
+ current_searchterm = "",
+ URL_SEARCH_PARAM = 'search',
+ URL_MARK_PARAM = 'highlight',
+ teaser_count = 0,
+
+ SEARCH_HOTKEY_KEYCODE = 83,
+ ESCAPE_KEYCODE = 27,
+ DOWN_KEYCODE = 40,
+ UP_KEYCODE = 38,
+ SELECT_KEYCODE = 13;
+
+ function hasFocus() {
+ return searchbar === document.activeElement;
+ }
+
+ function removeChildren(elem) {
+ while (elem.firstChild) {
+ elem.removeChild(elem.firstChild);
+ }
+ }
+
+ // Helper to parse a url into its building blocks.
+ function parseURL(url) {
+ var a = document.createElement('a');
+ a.href = url;
+ return {
+ source: url,
+ protocol: a.protocol.replace(':',''),
+ host: a.hostname,
+ port: a.port,
+ params: (function(){
+ var ret = {};
+ var seg = a.search.replace(/^\?/,'').split('&');
+ var len = seg.length, i = 0, s;
+ for (;i
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rust Basic Notes
+Toolchain
+Installation
+curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
+Cargo
+Cargo Basic Commands
+cargo new hello_world
+cargo run
+cargo build
+cargo run --release
+cargo build --release
+cargo check
+cargo generate-lockfile
+cargo fmt --check
+cargo clippy
+cargo test
+cargo install cargo-edit
+cargo install cargo-release
+cargo install cargo-tarpaulin
+cargo install cargo-watch
+cargo install cargo-workspaces
+Cargo release configuration:
+[workspace.metadata.release]
+# cargo install cargo-release
+# cargo release -x
+sign-commit = true
+sign-tag = true
+release = false
+push = false
+publish = false
+shared-version = true
+pre-release-commit-message = "chore(release): {{version}}"
+post-release-commit-message = "chore(release): {{version}}"
+tag-message = "{{tag_name}}"
+Cargo Cache
+~/.cargo/:
-
+
config.toml: global configuration.
+credentials.toml:cargo loginrelated file.
+.crates.toml/.crates2.json: installed package information.
+bin/: installed binaries.
+git/: installed rust git repositories. +-
+
git/db/: installed git repositories.
+git/checkouts/: branches of git repositories.
+
+registry/:crates.iometadata and packages. +-
+
registry/index/: metadata git repository.
+registry/cache/: dependencies cache (.crategzip files).
+registry/src/: package source files.
+
+
Cargo Configuration
+Cargo.toml:
-
+
cargo-features: 只能用于nightly版本的feature.
+[package]: 定义项目(package)的元信息. +-
+
name: 名称.
+version: 版本.
+authors: 开发作者.
+edition: Rust edition..
+rust-version: 支持的最小化 Rust 版本.
+description: 描述.
+documentation: 文档 URL.
+readme: README 文件的路径.
+homepage: 主页 URL.
+repository: 源代码仓库的 URL.
+license: 开源协议 License..
+license-file: License 文件的路径..
+keywords: 项目的关键词.
+categories: 项目分类.
+workspace: 工作空间 workspace 的路径.
+build: 构建脚本的路径.
+links: 本地链接库的名称.
+exclude: 发布时排除的文件.
+include: 发布时包含的文件.
+publish: 用于阻止项目的发布.
+metadata: 额外的配置信息，用于提供给外部工具.
+default-run: [cargo run] 所使用的默认可执行文件( binary ).
+autobins: 禁止可执行文件的自动发现.
+autoexamples: 禁止示例文件的自动发现.
+autotests: 禁止测试文件的自动发现.
+autobenches: 禁止 bench 文件的自动发现.
+resolver: 设置依赖解析器( dependency resolver).
+
+- Cargo target configuration:
+
-
+
[lib]: Library target.
+[[bin]]: Binary target.
+[[example]]: Example target.
+[[test]]: Test target.
+[[bench]]: Benchmark target.
+
+ - Dependency tables:
+
-
+
[dependencies]: 项目依赖包.
+[dev-dependencies]: +用于 examples、tests 和 benchmarks 的依赖包.
+[build-dependencies]: 用于构建脚本的依赖包.
+[target]: 平台特定的依赖包.
+
+ [badges]: 维护状态.
+[features]:features可以用于条件编译.
+[patch]: 推荐使用的依赖覆盖方式.
+[profile]: 编译器设置和优化.
+[workspace]: 工作空间的定义.
+
GitHub Action
+-
+
- Use tool to speed up compilation. +
name: CI
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+
+env:
+ CARGO_TERM_COLOR: always
+
+jobs:
+ test:
+ name: Test Suite
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ - uses: actions-rs/cargo@v1
+ with:
+ command: test
+ args: --all-features --workspace
+
+ rustfmt:
+ name: Rustfmt
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ components: rustfmt
+ - name: Check formatting
+ uses: actions-rs/cargo@v1
+ with:
+ command: fmt
+ args: --all -- --check
+
+ clippy:
+ name: Clippy
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ components: clippy
+ - name: Clippy check
+ uses: actions-rs/cargo@v1
+ with:
+ command: clippy
+ args: --all-targets --all-features --workspace -- -D warnings
+
+ docs:
+ name: Docs
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ - name: Check documentation
+ env:
+ RUSTDOCFLAGS: -D warnings
+ uses: actions-rs/cargo@v1
+ with:
+ command: doc
+ args: --no-deps --document-private-items --all-features --workspace
+
+ publish-dry-run:
+ name: Publish dry run
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ - uses: actions-rs/cargo@v1
+ with:
+ command: publish
+ args: --dry-run
+
+ coverage:
+ name: Code coverage
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v2
+ - name: Install Rust toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ toolchain: stable
+ profile: minimal
+ override: true
+ - name: Run cargo-tarpaulin
+ uses: actions-rs/tarpaulin@v0.1
+ with:
+ args: --all-features --workspace --ignore-tests --out Lcov
+ - name: Upload to Coveralls
+ if: ${{ github.event_name == 'push' }}
+ uses: coverallsapp/github-action@v1
+ with:
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ path-to-lcov: ./lcov.info
+Ownership
+Copy Trait
+Copyable type (implement Copy trait):
-
+
- Integer type. +
- Bool type. +
- Float type. +
- Char type. +
- Copyable Tuple type, e.g
(i32, i32).
+ - Reference type (borrowing ownership). +
Most these types store on stack +(including reference type with vtable).
++fn main() { + // Primitive type. + let a = 5; + let b = a; + + // Reference type. + let x: &str = "hello, world"; + let y = x; + + // Deep clone on `non-Copy` type. + let s1 = String::from("hello"); + let s2 = s1.clone(); + + // Correct. + println!("a = {}, b = {}", a, b); + println!("x = {}, y = {}", x, y); + println!("s1 = {}, s2 = {}", s1, s2); +}
+fn main() { + let s1 = String::from("hello"); + let s2 = s1; + + // Error[E0382]: use of moved value: `s1`. + // Move occurs because `s1` has type `std::string::String`, + // which does not implement the `Copy` trait. + println!("{}, world!", s1); +}
Reference Type
+Borrowing ownership with reference type:
+-
+
- At same time, only one mutable reference or multiple immutable reference. +
- Reference should be valid (rustc will report dangling reference error). +
+fn main() { + let s1 = String::from("hello"); + let len = calculate_length(&s1); + println!("The length of '{}' is {}.", s1, len); +} + +fn calculate_length(s: &String) -> usize { + s.len() + // Leave function without drop `s`, + // due to `s` not owner string. +}
Mutable reference:
+-
+
- Only one mutable reference for a value in a scope). +
- Can't mutable borrow an already immutable borrowed value. +
+fn main() { + let mut s = String::from("hello"); + change(&mut s); +} + +fn change(some_string: &mut String) { + some_string.push_str(", world"); +}
+fn main() { + let mut s = String::from("hello"); + + let r1 = &s; + let r2 = &s; + let r3 = &mut s; + + // Error. + println!("{}, {} and {}", r1, r2, r3); + // End of r1 and r2 borrowing. + + // Correct. + let r4 = &mut s; + println!("{}", r4); +}
String Type
+&str string slice reference type:
-
+
- Borrowing type. +
- UTF-8 encode (1 ~ 4 bytes). +
- String literal is
&strtype.
+
+#![allow(unused)] +fn main() { +let s = String::from("hello world"); +let len = s.len(); + +let hello = &s[0..5]; +let world = &s[6..11]; +let slice1 = &s[0..2]; +let slice2 = &s[..2]; +let slice3 = &s[4..len]; +let slice4 = &s[4..]; +let slice5 = &s[0..len]; +let slice6 = &s[..]; +}
String type:
-
+
- Ownership type. +
- UTF-8 encode (1 ~ 4 bytes). +
+fn main() { + let mut s = String::new(); + s.push_str("hello,world"); + s.push('!'); + assert_eq!(s,"hello,world!"); + + let mut s = "hello,world".to_string(); + s.push('!'); + assert_eq!(s,"hello,world!"); + + let mut s = String::from("你好, 世界"); + s.push('!'); + assert_eq!(s,"你好, 世界!"); + + let s1 = String::from("hello,"); + let s2 = String::from("world!"); + let s3 = s1 + &s2; + assert_eq!(s3,"hello,world!"); + + for c in "中国人".chars() { + println!("{}", c); + } +}
Struct Type
++#![allow(unused)] +fn main() { +struct User { + active: bool, + username: String, + email: String, + sign_in_count: u64, +} + +fn build_user(email: String, username: String) -> User { + User { + email, + username, + active: true, + sign_in_count: 1, + } +} + +let user1 = User { + email: String::from("someone@example.com"), + username: String::from("username123"), + active: true, + sign_in_count: 1, +}; + +let user2 = User { + email: String::from("another@example.com"), + ..user1 +}; +}
Tuple Struct
++#![allow(unused)] +fn main() { +struct Color(i32, i32, i32); +struct Point(i32, i32, i32); +let black = Color(0, 0, 0); +let origin = Point(0, 0, 0); +}
newtype: Wrap type into tuple struct:
-
+
- Make code more readable. +
- Implement 3rd traits for 3rd types. +
- Hide internal details of types. +
+#![allow(unused)] +fn main() { +struct Meters(u32); +}
Unit-like Struct
++#![allow(unused)] +fn main() { +struct AlwaysEqual; +let subject = AlwaysEqual; +impl SomeTrait for AlwaysEqual {} +}
Enum Type
++enum Message { + Quit, + Move { x: i32, y: i32 }, + Write(String), + ChangeColor(i32, i32, i32), +} + +fn main() { + let m1 = Message::Quit; + let m2 = Message::Move{x: 1, y: 1}; + let m3 = Message::ChangeColor(255, 255, 0); +}
+#![allow(unused)] +fn main() { +enum Option<T> { + Some(T), + None, +} + +fn plus_one(x: Option<i32>) -> Option<i32> { + match x { + None => None, + Some(i) => Some(i + 1), + } +} + +let five = Some(5); +let six = plus_one(five); +let none = plus_one(None); +}
Array Type
++let a: [i32; 5] = [1, 2, 3, 4, 5]; +let b = [3; 5]; +let slice: &[i32] = &a[1..3]; +assert_eq!(slice, &[2, 3]); + +fn main() { + let one = [1, 2, 3]; + let two: [u8; 3] = [1, 2, 3]; + let blank1 = [0; 3]; + let blank2: [u8; 3] = [0; 3]; + + let arrays: [[u8; 3]; 4] = [one, two, blank1, blank2]; + + for a in &arrays { + print!("{:?}: ", a); + + for n in a.iter() { + print!("\t{} + 10 = {}", n, n+10); + } + + let mut sum = 0; + + for i in 0..a.len() { + sum += a[i]; + } + + println!("\t({:?} = {})", a, sum); + } +}
Type Alias
++#![allow(unused)] +fn main() { +type Meters = i32; + +let x: u32 = 5; +let y: Meters = 5; + +println!("x + y = {}", x + y); +}
+#![allow(unused)] +fn main() { +type Result<T> = std::result::Result<T, std::io::Error>; +type Thunk = Box<dyn Fn() + Send + 'static>; + +let f: Thunk = Box::new(|| println!("hi")); +fn takes_long_type(f: Thunk) {} +fn returns_long_type() -> Thunk {} +}
Type Conversion
+From Trait
++use std::convert::From; + +#[derive(Debug)] +struct Number { + value: i32, +} + +impl From<i32> for Number { + fn from(item: i32) -> Self { + Number { value: item } + } +} + +fn main() { + let num = Number::from(30); + println!("My number is {:?}", num); + + let int = 5; + let num: Number = int.into(); + println!("My number is {:?}", num); +}
+use std::convert::TryFrom; +use std::convert::TryInto; + +#[derive(Debug, PartialEq)] +struct EvenNumber(i32); + +impl TryFrom<i32> for EvenNumber { + type Error = (); + + fn try_from(value: i32) -> Result<Self, Self::Error> { + if value % 2 == 0 { + Ok(EvenNumber(value)) + } else { + Err(()) + } + } +} + +fn main() { + // TryFrom + assert_eq!(EvenNumber::try_from(8), Ok(EvenNumber(8))); + assert_eq!(EvenNumber::try_from(5), Err(())); + + // TryInto + let result: Result<EvenNumber, ()> = 8i32.try_into(); + assert_eq!(result, Ok(EvenNumber(8))); + let result: Result<EvenNumber, ()> = 5i32.try_into(); + assert_eq!(result, Err(())); +}
Explicit Type Conversion
++fn main() { + let a = 3.1 as i8; + let b = 100_i8 as i32; + let c = 'a' as u8; + println!("{}, {}, {}", a, b, c) + + let x: i16 = 1500; + let x_: u8 = match x.try_into() { + Ok(x1) => x1, + Err(e) => { + println!("{:?}", e.to_string()); + 0 + } + }; +}
Implicit Type Conversion
+target.method():
-
+
- Call by value:
T::method(target).
+ - Call by reference:
T::method(&target)orT::method(&mut target).
+ - Call by deref: when
T: Deref<Target = U>, then(&T).method() => (&U).method().
+ - Length-non-determined collection to length-determined slice. +
- Panic. +
+#![allow(unused)] +fn main() { +let array: Rc<Box<[T; 3]>> = ...; +let first_entry = array[0]; +// 1. `Index` trait grammar sugar: array[0] => array.index(0). +// 2. Call by: value: `Rc<Box<[T; 3]>>` not impl `Index` trait. +// 3. Call by reference: `&Rc<Box<[T; 3]>>` not impl `Index` trait. +// 4. Call by reference: `&mut Rc<Box<[T; 3]>>` not impl `Index` trait. +// 5. Call by deref -> Call by value: `Box<[T; 3]>` not impl `Index` trait. +// 6. Call by deref -> Call by reference: `&Box<[T; 3]>` not impl `Index` trait. +// 7. Call by deref -> Call by reference: `&mut Box<[T; 3]>` not impl `Index` trait. +// 8. Call by deref -> Call by deref: `[T; 3]` not impl `Index` trait. +// 9. `[T; 3]` => `[T]` impl `Index` trait. +}
Dynamically Sized Type
+DST:
+-
+
- DST 无法单独被使用, 必须要通过
&/Box/Rc来间接使用.
+ str,[T],dyn Trait.
+
+#![allow(unused)] +fn main() { +// Error! +let s1: str = "Hello there!"; +let s2: str = "How's it going?"; + +// Ok. +let s3: &str = "on?" +let s4: Box<str> = "Hello there!".into(); +}
+#![allow(unused)] +fn main() { +// Error! +fn my_function(n: usize) { + let array = [123; n]; +} +}
+#![allow(unused)] +fn main() { +fn foobar_1(thing: &dyn MyThing) {} // OK. +fn foobar_2(thing: Box<dyn MyThing>) {} // OK. +fn foobar_3(thing: Rc<dyn MyThing>) {} // OK. +fn foobar_4(thing: MyThing) {} // ERROR! +}
Sized Trait
+Implicit sized trait:
++#![allow(unused)] +fn main() { +fn generic<T>(t: T) {} +// Auto-transform to by Rust compiler +fn generic<T: Sized>(t: T) {} +}
Dynamic sized generics:
++#![allow(unused)] +fn main() { +fn generic<T: ?Sized>(t: &T) {} +}
Flow Control
+If Statement
+if expression:
+#![allow(unused)] +fn main() { +let number = if condition { + 5 +} else { + 6 +}; +}
if let expression:
+#![allow(unused)] +fn main() { +let o = Some(3); +let v = if let Some(x) = o { + x +} else { + 0 +}; +}
Loop Statement
+For Loop Statement
++#![allow(unused)] +fn main() { +for i in 1..=5 {} +for _ in 0..10 {} +for item in collection {} +for item in &collection {} +for item in &mut collection {} +for (i, v) in collection.iter().enumerate() {} +}
While Loop Statement
++fn main() { + let mut n = 0; + + while n <= 5 { + println!("{}!", n); + n = n + 1; + } +}
Loop Expression
++fn main() { + let mut counter = 0; + + let result = loop { + counter += 1; + + if counter == 10 { + break counter * 2; + } + }; + + println!("The result is {}", result); +}
Pattern Matching
++#![allow(unused)] +fn main() { +match target { + pattern1 => expression1, + pattern2 => { + statement1; + statement2; + expression2 + }, + _ => expression3 +} + +if let pattern = target { + statement; + expression +} + +while let pattern = target { + statement; +} +}
Enum Pattern Matching
++enum Action { + Say(String), + MoveTo(i32, i32), + ChangeColorRGB(u16, u16, u16), +} + +fn main() { + let actions = [ + Action::Say("Hello Rust".to_string()), + Action::MoveTo(1,2), + Action::ChangeColorRGB(255,255,0), + ]; + + for action in actions { + match action { + Action::Say(s) => { + println!("{}", s); + }, + Action::MoveTo(x, y) => { + println!("point from (0, 0) move to ({}, {})", x, y); + }, + Action::ChangeColorRGB(r, g, _) => { + println!("change color into '(r:{}, g:{}, b:0)', 'b' has been ignored", + r, g, + ); + } + } + } +}
Tuple Pattern Matching
++fn main() { + let numbers = (2, 4, 8, 16, 32); + + match numbers { + (first, .., last) => { + println!("Some numbers: {}, {}", first, last); + }, + } +}
Struct Pattern Matching
++struct Point { + x: i32, + y: i32, + z: i32, +} + +fn main() { + let p = Point { x: 0, y: 7, z: 0 }; + let Point { x: a, y: b, z: c } = p; + assert_eq!(0, a); + assert_eq!(7, b); + assert_eq!(0, c); + + let origin = Point { x: 0, y: 0, z: 0 }; + match origin { + Point { x, .. } => println!("x is {}", x), + } +}
+fn main() { + let p = Point { x: 0, y: 7 }; + + match p { + Point { x, y: 0 } => println!("On the x axis at {}", x), + Point { x: 0, y } => println!("On the y axis at {}", y), + Point { x, y } => println!("On neither axis: ({}, {})", x, y), + } +}
Match Guard
+Combine pattern matching and if expression:
+#![allow(unused)] +fn main() { +let num = Some(4); + +match num { + Some(x) if x < 5 => println!("less than five: {}", x), + Some(x) => println!("{}", x), + None => (), +} +}
Match Assignment
+Combine pattern matching and @ expression:
+#![allow(unused)] +fn main() { +enum Message { + Hello { id: i32 }, +} + +let msg = Message::Hello { id: 5 }; + +match msg { + Message::Hello { id: id_variable @ 3..=7 } => { + println!("Found an id in range: {}", id_variable) + }, + Message::Hello { id: 10..=12 } => { + println!("Found an id in another range") + }, + Message::Hello { id } => { + println!("Found some other id: {}", id) + }, +} +}
+struct Point { + x: i32, + y: i32, +} + +fn main() { + let p @ Point {x: px, y: py } = Point {x: 10, y: 23}; + println!("x: {}, y: {}", px, py); + println!("{:?}", p); + + let point = Point {x: 10, y: 5}; + if let p @ Point {x: 10, y} = point { + println!("x is 10 and y is {} in {:?}", y, p); + } else { + println!("x was not 10 :("); + } +}
Method
++#![allow(unused)] +fn main() { +struct Circle { + x: f64, + y: f64, + radius: f64, +} + +impl Circle { + fn new(x: f64, y: f64, radius: f64) -> Circle { + Circle { + x, + y, + radius, + } + } + + fn area(&self) -> f64 { + std::f64::consts::PI * (self.radius * self.radius) + } +} +}
+enum Message { + Quit, + Move { x: i32, y: i32 }, + Write(String), + ChangeColor(i32, i32, i32), +} + +impl Message { + fn call(&self) {} +} + +fn main() { + let m = Message::Write(String::from("hello")); + m.call(); +}
Self
+-
+
self: 所有权转移.
+&self: 不可变借用.
+&mut self: 可变借用.
+
+pub struct Rectangle { + width: u32, + height: u32, +} + +impl Rectangle { + pub fn new(width: u32, height: u32) -> Self { + Rectangle { width, height } + } + pub fn width(&self) -> u32 { + return self.width; + } + pub fn height(&self) -> u32 { + return self.height; + } +} + +fn main() { + let rect = Rectangle::new(30, 50); + println!("{}", rect.width()); + println!("{}", rect.height()); +}
Generics
++#![allow(unused)] +fn main() { +enum Option<T> { + Some(T), + None, +} + +enum Result<T, E> { + Ok(T), + Err(E), +} + +struct Point<T> { + x: T, + y: T, +} + +impl<T> Point<T> { + fn x(&self) -> &T { + &self.x + } + + fn mixup<U>(self, other: Point<U>) {} +} + +impl Point<f32> { + fn distance_from_origin(&self) -> f32 { + (self.x.powi(2) + self.y.powi(2)).sqrt() + } +} + + +fn add<T: std::ops::Add<T, Output = T>>(a:T, b:T) -> T { + a + b +} + +fn largest<T: PartialOrd>(list: &[T]) -> T {} +}
-
+
- TurboFish:
+
-
+
generics_struct::<T>::method().
+struct.generics_method::<T>().
+
+ - Use associated types in traits. +
Traits
++pub struct Post { + pub username: String, + pub content: String +} + +pub trait Summary { + fn summarize_author(&self) -> String; + + fn summarize(&self) -> String { + format!("(Read more from {}...)", self.summarize_author()) + } +} + +impl Summary for Post { + fn summarize_author(&self) -> String { + format!("@{}", self.username) + } +} + +fn main() { + let post = Post{username: "username".to_string(),content: "content".to_string()}; + println!("1 new post: {}", post.summarize()); +}
Orphan Rule
+Rust can’t implement external traits on external types:
+can’t implement the Display trait on Vec<T> in some_package crate,
+because Display and Vec<T> are both defined out of some_package.
+This restriction is part of a property of programs called coherence,
+ensures that other people’s code can’t break your code and vice versa.
Trait Bound
++#![allow(unused)] +fn main() { +fn notify(item: &impl Summary) {} +fn notify(item: &(impl Summary + Display)) {} +fn notify<T: Summary>(item: &T) {} +fn notify<T: Summary + Display>(item: &T) {} +fn notify<T, U>(t: &T, u: &U) -> i32 + where T: Display + Clone, + U: Clone + Debug +{} +}
+#![allow(unused)] +fn main() { +trait SomeTrait: BoundTrait {} +}
+#![allow(unused)] +fn main() { +// 可以对任何实现了 Display 特征的类型调用 ToString 特征中方法. +impl<T: Display> ToString for T {} +}
Trait Derive
++#![allow(unused)] +fn main() { +#[derive(Debug)] +#[derive(PartialEq)] +#[derive(Eq)] +#[derive(PartialOrd)] +#[derive(Ord)] +#[derive(Clone)] +#[derive(Copy)] +#[derive(Hash)] +#[derive(Default)] +}
+#![allow(unused)] +fn main() { +trait Person { + fn name(&self) -> String; +} + +trait Student: Person { + fn university(&self) -> String; +} + +trait Programmer { + fn fav_language(&self) -> String; +} + +trait CompSciStudent: Programmer + Student { + fn git_username(&self) -> String; +} + +fn comp_sci_student_greeting(student: &dyn CompSciStudent) -> String { + format!( + "My name is {} and I attend {}. My language is {}. My Git username is {}", + student.name(), + student.university(), + student.fav_language(), + student.git_username() + ) +} +}
Trait Object
+-
+
- Define trait object:
+
-
+
Box<dyn some_trait>.
+&dyn some_trait.
+
+ - A trait can have trait object only when
+it is
object safe: +-
+
- all methods can't return
Self.
+ - all methods can't be generics. +
+ - all methods can't return
- Trait object has
'staticlifetime.
+ - Trait object stand for dynamic distributing (runtime), +generics stand for static distributing (compile time). +
+trait Draw { + fn draw(&self) -> String; +} + +impl Draw for u8 { + fn draw(&self) -> String { + format!("u8: {}", *self) + } +} + +impl Draw for f64 { + fn draw(&self) -> String { + format!("f64: {}", *self) + } +} + +fn draw1(x: Box<dyn Draw>) { + x.draw(); +} + +fn draw2(x: &dyn Draw) { + x.draw(); +} + +fn main() { + let x = 1.1f64; + let y = 8u8; + + draw1(Box::new(x)); + draw1(Box::new(y)); + draw2(&x); + draw2(&y); +}
Associated Types
+Associated types make code become readable and concise:
++#![allow(unused)] +fn main() { +trait Container<A,B> { + fn contains(&self,a: A,b: B) -> bool; +} + +fn difference<A,B,C>(container: &C) -> i32 + where + C : Container<A,B> {} +}
+#![allow(unused)] +fn main() { +trait Container{ + type A; + type B; + fn contains(&self, a: &Self::A, b: &Self::B) -> bool; +} + +fn difference<C: Container>(container: &C) {} +}
For all generic trait,
+use associated types better than <T>.
Common Traits
+-
+
std::fmt::Display(better thanstd::string::ToString).
+std::fmt::Debug.
+std::ops::Add/Mul/Div/BitAnd/BitOr/Not/Neg: operators overload.
+std::ops::Fn/FnMut/FnOnce.
+std::ops::Deref.
+std::ops::Drop.
+std::clone::Clone.
+std::iter::Iterator.
+
std::prelude:
-
+
std::marker::{Copy, Send, Sized, Sync, Unpin}.
+std::ops::{Drop, Fn, FnMut, FnOnce}.
+std::mem::drop.
+std::boxed::Box.
+std::borrow::ToOwned.
+std::clone::Clone.
+std::cmp::{PartialEq, PartialOrd, Eq, Ord}.
+std::convert::{AsRef, AsMut, Into, From}.
+std::default::Default.
+std::iter::{Iterator, Extend, IntoIterator, DoubleEndedIterator, ExactSizeIterator}.
+std::option::Option::{self, Some, None}.
+std::result::Result::{self, Ok, Err}.
+std::string::{String, ToString}.
+std::vec::Vec.
+std::convert::{TryFrom, TryInto}.
+std::iter::FromIterator.
+
+#![allow(unused)] +fn main() { +use std::io::prelude::*; +}
Collection
+Vector
+Create and Insert:
++#![allow(unused)] +fn main() { +let mut v = Vec::new(); +v.push(1); +}
Access and Get:
++#![allow(unused)] +fn main() { +let v = vec![1, 2, 3, 4, 5]; + +let third: &i32 = &v[2]; +println!("3rd: {}", third); + +match v.get(2) { + Some(third) => println!("3rd: {}", third), + None => println!("None."), +} +}
Visit:
++#![allow(unused)] +fn main() { +let v = vec![1, 2, 3]; + +for i in &v { + println!("{}", i); +} +}
Visit and Mutate:
++#![allow(unused)] +fn main() { +let mut v = vec![1, 2, 3]; + +for i in &mut v { + *i += 10 +} +}
Store different types:
++enum IpAddr { + V4(String), + V6(String) +} + +fn main() { + let v = vec![ + IpAddr::V4("127.0.0.1".to_string()), + IpAddr::V6("::1".to_string()) + ]; + + for ip in v { + show_addr(ip) + } +} + +fn show_addr(ip: IpAddr) { + println!("{:?}",ip); +}
HashMap
++#![allow(unused)] +fn main() { +use std::collections::HashMap; +}
+#![allow(unused)] +fn main() { +// Create. +let mut scores = HashMap::new(); + +// Insert. +scores.insert(String::from("Blue"), 10); +scores.insert(String::from("Yellow"), 50); +scores.entry("Red").or_insert(5); + +// Get. +let team_name = String::from("Blue"); +let score: Option<&i32> = scores.get(&team_name); + +// Visit +for (key, value) in &scores { + println!("{}: {}", key, value); +} + +// Transform. +let from_list: HashMap<_,_> = some_list.into_iter().collect(); +}
HashSet
+-
+
- insert. +
- contains. +
- union. +
- difference. +
- intersection. +
- symmetric_difference. +
Error Handling
+Result Type
++use std::fs::File; +use std::io::ErrorKind; + +fn main() { + let f = File::open("hello.txt"); + + let f = match f { + Ok(file) => file, + Err(error) => match error.kind() { + ErrorKind::NotFound => match File::create("hello.txt") { + Ok(fc) => fc, + Err(e) => panic!("Problem creating the file: {:?}", e), + }, + other_error => panic!("Problem opening the file: {:?}", other_error), + }, + }; +}
Result Type Compositor
+-
+
or: logic or.
+and: logic and.
+or_else: logic or function.
+and_then: logic and function.
+filter:Optionfilter function.
+map:Ok/Somemap function.
+map_or:Ok/Somemap function with defaults value.
+map_or_else:Ok/Somemap function with defaults function.
+map_err:Errmap function.
+ok_or:Option->Resultwith error message.
+ok_or_else:Option->Resultwith error message function.
+
Error Handling Macro
+? for Result type:
+#![allow(unused)] +fn main() { +use std::fs::File; +use std::io; +use std::io::Read; + +fn open_file() -> Result<File, Box<dyn std::error::Error>> { + let mut f = File::open("hello.txt")?; + Ok(f) +} + +fn read_username_from_file() -> Result<String, io::Error> { + let mut s = String::new(); + File::open("hello.txt")?.read_to_string(&mut s)?; + Ok(s) +} +}
? for Option type:
+#![allow(unused)] +fn main() { +fn last_char_of_first_line(text: &str) -> Option<char> { + text.lines().next()?.chars().last() +} +}
Error Trait
+Standard Error Trait
++#![allow(unused)] +fn main() { +use std::fmt::{Debug, Display}; + +pub trait Error: Debug + Display { + fn source(&self) -> Option<&(Error + 'static)> { ... } +} +}
+use std::fs::read_to_string; +use std::error::Error; + +fn main() -> Result<(), Box<dyn Error>> { + let html = render()?; + println!("{}", html); + Ok(()) +} + +fn render() -> Result<String, Box<dyn Error>> { + let file = std::env::var("MARKDOWN")?; + let source = read_to_string(file)?; + Ok(source) +}
Custom Error Type
++use std::error; +use std::fmt; + +#[derive(Debug)] +struct AppError; + +impl fmt::Display for AppError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "An Error Occurred, Please Try Again!") + } +} + +impl error::Error for AppError { + fn description(&self) -> &str { + "Invalid App" + } + + fn source(&self) -> Option<&(dyn error::Error + 'static)> { + None + } + + fn cause(&self) -> Option<&dyn error::Error> { + None + } +} + +fn produce_error() -> Result<(), AppError> { + Err(AppError) +} + +fn main(){ + match produce_error() { + Err(e) => eprintln!("{}", e), + _ => println!("No error"), + } + + eprintln!("{:?}", produce_error()); // Err({ file: src/main.rs, line: 17 }) +}
Convert From Standard Error
++use std::fs::File; +use std::io::{self, Read}; +use std::num; + +#[derive(Debug)] +struct AppError { + kind: String, + message: String, +} + +impl From<io::Error> for AppError { + fn from(error: io::Error) -> Self { + AppError { + kind: String::from("io"), + message: error.to_string(), + } + } +} + +impl From<num::ParseIntError> for AppError { + fn from(error: num::ParseIntError) -> Self { + AppError { + kind: String::from("parse"), + message: error.to_string(), + } + } +} + +fn main() -> Result<(), AppError> { + let mut file = File::open("hello_world.txt")?; + + let mut content = String::new(); + file.read_to_string(&mut content)?; + + let _number: usize; + _number = content.parse()?; + + Ok(()) +} + + +// --------------- 上述代码运行后的可能输出 --------------- +// 01. 若 hello_world.txt 文件不存在 +// Error: AppError { kind: "io", message: "No such file or directory" } +// 02. 若用户没有相关的权限访问 hello_world.txt +// Error: AppError { kind: "io", message: "Permission denied" } +// 03. 若 hello_world.txt 包含有非数字的内容，例如 Hello, world! +// Error: AppError { kind: "parse", message: "invalid digit found in string" }
Format Print
+Format Print Macros
+-
+
print!.
+println!.
+eprint!.
+eprintln!.
+format!.
+
+#![allow(unused)] +fn main() { +println!("Hello"); // => "Hello" +println!("Hello, {}!", "world"); // => "Hello, world!" +println!("The number is {}", 1); // => "The number is 1" +println!("{:?}", (3, 4)); // => "(3, 4)" +println!("{value}", value=4); // => "4" +println!("{} {}", 1, 2); // => "1 2" +println!("{:04}", 42); // => "0042" with leading zeros +}
+fn main() { + let s = "hello"; + println!("{}, world", s); + let s1 = format!("{}, world", s); + print!("{}", s1); + print!("{}\n", "!"); +}
Format Print Placeholder
+-
+
{}.
+{:?}.
+{:#?}.
+- Index placeholder. +
- Alias placeholder. +
+fn main() { + println!("{1}{}{0}{}", 1, 2); // => 2112 + println!("{name} {}", 1, name = 2); // => "2 1" + println!("{a} {c} {b}", a = "a", b = 'b', c = 3); // => "a 3 b" +}
-
+
- Pad placeholder. +
+fn main() { + // 以下全部输出 "Hello x !" + // 为"x"后面填充空格, 补齐宽度5 + println!("Hello {:5}!", "x"); + // 使用参数5来指定宽度 + println!("Hello {:1$}!", "x", 5); + // 使用x作为占位符输出内容, 同时使用5作为宽度 + println!("Hello {1:0$}!", 5, "x"); + // 使用有名称的参数作为宽度 + println!("Hello {:width$}!", "x", width = 5); + + // 使用参数5为参数x指定宽度, 同时在结尾输出参数5 => Hello x !5 + println!("Hello {:1$}!{}", "x", 5); + + // 宽度是5 => Hello 5! + println!("Hello {:5}!", 5); + // 显式的输出正号 => Hello +5! + println!("Hello {:+}!", 5); + // 宽度5, 使用0进行填充 => Hello 00005! + println!("Hello {:05}!", 5); + // 负号也要占用一位宽度 => Hello -0005! + println!("Hello {:05}!", -5); +}
-
+
- Alignment placeholder. +
+fn main() { + // 以下全部都会补齐5个字符的长度 + // 左对齐 => Hello x ! + println!("Hello {:<5}!", "x"); + // 右对齐 => Hello x + println!("Hello {:>5}!", "x"); + // 居中对齐 => Hello x ! + println!("Hello {:^5}!", "x"); + + // 对齐并使用指定符号填充 => Hello x&&&&! + // 指定符号填充的前提条件是必须有对齐字符 + println!("Hello {:&<5}!", "x"); +}
-
+
- Precision placeholder. +
+fn main() { + let v = 3.1415926; + // 保留小数点后两位 => 3.14 + println!("{:.2}", v); + // 带符号保留小数点后两位 => +3.14 + println!("{:+.2}", v); + // 不带小数 => 3 + println!("{:.0}", v); + // 通过参数来设定精度 => 3.1416, 相当于{:.4} + println!("{:.1$}", v, 4); + + let s = "hello I'm some one"; + // 保留字符串前三个字符 => hel + println!("{:.3}", s); + // {:.*} 接收两个参数, 第一个是精度, 第二个是被格式化的值 => Hello abc! + println!("Hello {:.*}!", 3, "abcdefg"); +}
-
+
- Radix placeholder:
boxXeE. +-
+
fmt::Binarytrait.
+fmt::Octaltrait.
+fmt::LowerHextrait.
+fmt::UpperHextrait.
+fmt::LowerExptrait.
+fmt::UpperExptrait.
+
+
+fn main() { + // 二进制 => 0b11011! + println!("{:#b}!", 27); + // 八进制 => 0o33! + println!("{:#o}!", 27); + // 十进制 => 27! + println!("{}!", 27); + // 小写十六进制 => 0x1b! + println!("{:#x}!", 27); + // 大写十六进制 => 0x1B! + println!("{:#X}!", 27); + + // 不带前缀的十六进制 => 1b! + println!("{:x}!", 27); + + // 使用0填充二进制, 宽度为10 => 0b00011011! + println!("{:#010b}!", 27); + + println!("{:2e}", 1000000000); // => 1e9 + println!("{:2E}", 1000000000); // => 1E9 +}
Debug Trait
++#[derive(Debug)] +struct Person { + name: String, + age: u8 +} + +fn main() { + let i = 3.1415926; + let s = String::from("hello"); + let v = vec![1, 2, 3]; + let p = Person{name: "name".to_string(), age: 18}; + println!("{:?}, {:?}, {:?}, {:?}", i, s, v, p); +}
Display Trait
++use std::fmt; + +struct Person { + name: String, + age: u8, +} + +impl fmt::Display for Person { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!( + f, + "My name is {}, {} year old.", + self.name, self.age + ) + } +} + +fn main() { + let p = Person { + name: "name".to_string(), + age: 18, + }; + + println!("{}", p); +}
Lifetime
+显式地使用生命周期, 可以让编译器正确地认识到多个引用之间的关系.
++#![allow(unused)] +fn main() { +&i32 // 一个引用 +&'a i32 // 具有显式生命周期的引用 +&'a mut i32 // 具有显式生命周期的可变引用 +}
+#![allow(unused)] +fn main() { +struct ImportantExcerpt<'a> { + part: &'a str, +} + + +fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { + if x.len() > y.len() { + x + } else { + y + } +} +}
Function Lifetime
+函数或者方法中,
+参数的生命周期被称为输入生命周期,
+返回值的生命周期被称为输出生命周期:
-
+
- 每一个引用参数都会获得独自的生命周期:
+
fn foo<'a, 'b>(x: &'a i32, y: &'b i32).
+ - 若只有一个输入生命周期, 则该生命周期会被赋给所有输出生命周期. +
- 若存在多个输入生命周期, 且其中一个是
&self/&mut self, +则&self生命周期被赋给所有输出生命周期 (除非显式地声明输出生命周期).
+
Static Lifetime
+生命周期'static表示持续整个程序,
+例如字符串字面量和特征对象.
Lifetime Constraint
+-
+
'a: 'b:'a生命周期更长.
+T: 'a:T生命周期更长.
+
Closure
+Function Parameter Closure
+改变捕获变量的所有权 (FnOnce):
++fn fn_once<F>(func: F) +where + F: FnOnce(usize) -> bool + Copy, +{ + println!("{}", func(3)); + println!("{}", func(4)); +} + +fn main() { + let x = vec![1, 2, 3]; + fn_once(|z|{z == x.len()}) +}
可变借用捕获 (FnMut):
++fn main() { + let mut s = String::new(); + + let update_string = |str| s.push_str(str); + + exec(update_string); + + println!("{:?}",s); +} + +fn exec<'a, F: FnMut(&'a str)>(mut f: F) { + f("hello") +}
不可变借用捕获 (Fn):
++fn main() { + let s = "hello, ".to_string(); + + let update_string = |str| println!("{},{}",s,str); + + exec(update_string); + + println!("{:?}",s); +} + +fn exec<'a, F: Fn(String) -> ()>(f: F) { + f("world".to_string()) +}
-
+
- 所有闭包都自动实现了
FnOnce特征, 因此任何一个闭包都至少可以被调用一次.
+ - 没有移出所捕获变量的所有权的闭包自动实现了
FnMut特征.
+ - 不需要对捕获变量进行改变的闭包自动实现了
Fn特征.
+
Function Return Closure
++#![allow(unused)] +fn main() { +fn factory() -> impl Fn(i32) -> i32 { + let num = 5; + |x| x + num +} +}
+#![allow(unused)] +fn main() { +fn factory(x:i32) -> Box<dyn Fn(i32) -> i32> { + let num = 5; + + if x > 1{ + Box::new(move |x| x + num) + } else { + Box::new(move |x| x - num) + } +} +}
Iterator
++#![allow(unused)] +fn main() { +let arr = [1, 2, 3]; + +for v in arr.into_iter() { + println!("{}", v); +} +}
+fn main() { + let arr = [1, 2, 3]; + let mut arr_iter = arr.into_iter(); + + assert_eq!(arr_iter.next(), Some(1)); + assert_eq!(arr_iter.next(), Some(2)); + assert_eq!(arr_iter.next(), Some(3)); + assert_eq!(arr_iter.next(), None); +}
Iterator Trait
++#![allow(unused)] +fn main() { +pub trait Iterator { + type Item; + + fn next(&mut self) -> Option<Self::Item>; +} + +impl<I: Iterator> IntoIterator for I { + type Item = I::Item; + type IntoIter = I; + + #[inline] + fn into_iter(self) -> I { + self + } +} +}
-
+
iter: 不可变借用.
+iter_mut: 可变借用.
+into_iter: 改变所有权.
+
+#![allow(unused)] +fn main() { +fn iter(&self) -> Iter // Iter implements Iterator<Item = &U> +fn iter_mut(&mut self) -> IterMut // IterMut implements Iterator<Item = &mut U> +fn into_iter(self) -> IntoIter // IntoIter implements Iterator<Item = U> +}
+fn main() { + let values = vec![1, 2, 3]; + + for v in values.into_iter() { + println!("{}", v) + } + + // 下面的代码将报错. + // println!("{:?}",values); + + let values = vec![1, 2, 3]; + let _values_iter = values.iter(); + + // 不会报错. + println!("{:?}", values); + + let mut values = vec![1, 2, 3]; + // 对 values 中的元素进行可变借用. + let mut values_iter_mut = values.iter_mut(); + + // 取出第一个元素, 并修改为0. + if let Some(v) = values_iter_mut.next() { + *v = 0; + } + + // 输出 [0, 2, 3]. + println!("{:?}", values); +}
Implement iterator:
++struct Counter { + count: u32, +} + +impl Counter { + fn new() -> Counter { + Counter { count: 0 } + } +} + +impl Iterator for Counter { + type Item = u32; + + fn next(&mut self) -> Option<Self::Item> { + if self.count < 5 { + self.count += 1; + Some(self.count) + } else { + None + } + } +} + +fn main() { + let mut counter = Counter::new(); + assert_eq!(counter.next(), Some(1)); + assert_eq!(counter.next(), Some(2)); + assert_eq!(counter.next(), Some(3)); + assert_eq!(counter.next(), Some(4)); + assert_eq!(counter.next(), Some(5)); + assert_eq!(counter.next(), None); + + let sum: u32 = Counter::new() + .zip(Counter::new().skip(1)) + .map(|(a, b)| a * b) + .filter(|x| x % 3 == 0) + .sum(); + assert_eq!(18, sum); +}
Adapter Methods
+-
+
- 消费性适配器: 获取迭代器的所有权, 并消耗迭代器中所有元素.
+
-
+
collect::<T>().
+- fold. +
- partition. +
sum::<T>().
+
+ - 迭代性适配器: 惰性方法 (Lazy Iterator)
+
-
+
- enumerate. +
- filter. +
- filter_map. +
- map. +
- take_while. +
- zip. +
+ - Ordinary iterator methods:
+
-
+
- Iterator::any. +
- Iterator::find. +
+
More adapter methods see Iterator trait
+documentation.
+fn main() { + let v1 = vec![1, 2, 3]; + let v1_iter = v1.iter(); + let total: i32 = v1_iter.sum(); + assert_eq!(total, 6); + + // v1_iter 是借用了 v1, 因此 v1 可以照常使用. + println!("{:?}",v1); + + // 以下代码会报错, 因为 `sum` 拿到了迭代器 `v1_iter` 的所有权. + // println!("{:?}",v1_iter); +}
+fn main() { + let v1: Vec<i32> = vec![1, 2, 3]; + let v2: Vec<_> = v1.iter().map(|x| x + 1).collect(); + assert_eq!(v2, vec![2, 3, 4]); +}
+use std::collections::HashMap; + +fn main() { + let names = ["name1", "name2"]; + let ages = [18, 18]; + let folks: HashMap<_, _> = names.into_iter().zip(ages.into_iter()).collect(); + println!("{:?}",folks); +}
Smart Pointer
+Box Type
+Box<T> 将一个值分配到堆上, 然后在栈上保留一个智能指针指向堆上数据:
-
+
- 实现转移所有权时的零拷贝. +
- 将不定长类型转换为定长类型. +
+fn main() { + // 在栈上创建一个长度为 1000 的数组. + let arr = [0;1000]; + // 将 arr 所有权转移 arr1, 由于 `arr` 分配在栈上, 因此直接重新深拷贝了一份数据. + let arr1 = arr; + + // arr 和 arr1 都拥有各自的栈上数组, 因此不会报错. + println!("{:?}", arr.len()); + println!("{:?}", arr1.len()); + + // 在堆上创建一个长度为 1000 的数组, 然后使用一个智能指针指向它. + let arr = Box::new([0;1000]); + // 将堆上数组的所有权转移给 arr1, 由于数据在堆上, 因此仅仅拷贝了智能指针的结构体, 底层数据并没有被拷贝. + // 所有权顺利转移给 arr1, arr 不再拥有所有权. + let arr1 = arr; + println!("{:?}", arr1.len()); + // 由于 arr 不再拥有底层数组的所有权, 因此下面代码将报错. + // println!("{:?}", arr.len()); +}
+#![allow(unused)] +fn main() { +enum List { + Cons(i32, Box<List>), + Nil, +} +}
Deref Trait
+-
+
&smart_pointer+=>smart_pointer.defer().
+*smart_pointer+=>*(smart_pointer.defer()).
+smart_pointer.method()+=>(&smart_pointer).method()+=>(smart_pointer.defer()).method().
+- When
T: Deref<Target=U>, then&T => &U.
+ - When
T: DerefMut<Target=U>, then&mut T => &mut U.
+ - When
T: Deref<Target=U>, then&mut T => &U.
+
+use core::ops::{self}; +use crate::str::{self, from_boxed_utf8_unchecked}; +use crate::vec::Vec; + +struct String { + vec: Vec<u8>, +} + +impl ops::Deref for String { + type Target = str; + + fn deref(&self) -> &str { + unsafe { str::from_utf8_unchecked(&self.vec) } + } +} + +struct MyBox<T>(T); + +impl<T> MyBox<T> { + fn new(x: T) -> MyBox<T> { + MyBox(x) + } +} + +impl<T> ops::Deref for MyBox<T> { + type Target = T; + + fn deref(&self) -> &Self::Target { + &self.0 + } +} + +fn main() { + let x = MyBox::new(5); + assert_eq!(5, *x); + // => *(x.deref()) + // => *(&x.0) + // => x.0 + + let s = MyBox::new(String::from("hello world")); + display(&s); + // => &MyBox + // => MyBox.deref() + // => &String + // => String.deref() + // => &str + + let hello_world = MyBox::new(String::from("hello, world")); + let s1: &str = &hello_world; + // => &MyBox<String> + // => MyBox<String>.deref() + // => &String + // => String.deref() + // => &str + let s2: String = hello_world.to_string(); + // => MyBox<String>.to_string() + // => (&MyBox<String>).to_string() + // => (MyBox<String>.defer()).to_string() + // => (&String).to_string() + let ptr: *const u8 = hello_world.as_ptr(); + // => MyBox<String>.as_ptr() + // => (&MyBox<String>).as_ptr() + // => (MyBox<String>.defer()).as_ptr() + // => (&String).as_ptr() + // => (String.defer()).as_ptr() + // => (&str).as_ptr() +} + +fn display(s: &str) { + println!("{}", s); +}
Drop Trait
+Drop order:
+-
+
- 变量级别, 按照逆序的方式, 先创建的变量后 drop. +
- 结构体内部, 按照顺序的方式, 结构体中的字段按照定义中的顺序依次 drop. +
Reference Counting Type
+通过引用计数的方式, 允许一个数据资源在同一时刻拥有多个所有者.
++use std::rc::Rc; + +fn main() { + let a = Rc::new(String::from("hello, world")); + let b = Rc::clone(&a); // 复制了智能指针并增加了引用计数, 并没有克隆底层数据. + assert_eq!(2, Rc::strong_count(&a)); + assert_eq!(Rc::strong_count(&a), Rc::strong_count(&b)) +}
-
+
Rc/Arc是不可变引用, 无法修改它指向的值.
+Rc<T>是一个智能指针, 实现了Deref特征, 可以直接使用T.
+- 一旦最后一个拥有者消失, 则资源会自动被回收. +
Arc: Atomic reference counting.
+
+use std::sync::Arc; +use std::thread; + +fn main() { + let s = Arc::new(String::from("Multiple threads walker")); + + for _ in 0..10 { + let s = Arc::clone(&s); + let handle = thread::spawn(move || { + println!("{}", s) + }); + } +}
Cell and RefCell Type
+Cell for copyable type.
+use std::cell::Cell; + +fn main() { + let c = Cell::new("abc"); + let one = c.get(); + c.set("xyz"); + let two = c.get(); + println!("{}, {}", one, two); // abc, xyz +}
+#![allow(unused)] +fn main() { +use std::cell::Cell; + +fn retain_even(nums: &mut Vec<i32>) { + let slice: &[Cell<i32>] = Cell::from_mut(&mut nums[..]) + .as_slice_of_cells(); + + let mut i = 0; + + for num in slice.iter().filter(|num| is_even(num.get())) { + slice[i].set(num.get()); + i += 1; + } + + nums.truncate(i); +} +}
RefCell for borrowing reference:
-
+
- 实现内部可变性: 不可变值的可变借用.
+
imut_self.refcell_member.borrow_mut().changeMember().
+ Rc<RefCell<T>>: 实现多个可变数据所有者.
+- 实现编译期可变借用与不可变借用共存,
+但会引起运行时
panic.
+
+use std::cell::RefCell; + +fn main() { + let s = RefCell::new(String::from("hello, world")); + let s1 = s.borrow(); + let s2 = s.borrow_mut(); + + println!("{}, {}", s1, s2); +}
通过包裹一层 RefCell,
+将不可变借用 &self 的成员成为一个可变值,
+然后实现修改:
+use std::cell::RefCell; + +pub trait Messenger { + fn send(&self, msg: String); +} + +pub struct MsgQueue { + msg_cache: RefCell<Vec<String>>, +} + +impl Messenger for MsgQueue { + fn send(&self, msg: String) { + self.msg_cache.borrow_mut().push(msg) + } +} + +fn main() { + let mq = MsgQueue { + msg_cache: RefCell::new(Vec::new()), + }; + mq.send("hello, world".to_string()); +}
Circle Reference
+Weak 通过 use std::rc::Weak 引入, 具有以下特点:
-
+
- 可访问, 但没有所有权, 不增加引用计数, 不影响 drop. +
- 可由
Rc<T>调用downgrade方法转换成Weak<T>.
+ Weak<T>可使用upgrade方法转换成Option<Rc<T>>, +如果资源已经被释放, 则Option的值是None.
+- 常用于解决循环引用的问题. +
+use std::cell::RefCell; +use std::rc::{Rc, Weak}; + +#[derive(Debug)] +struct Node { + value: i32, + parent: RefCell<Weak<Node>>, + children: RefCell<Vec<Rc<Node>>>, +} + +fn main() { + let leaf = Rc::new(Node { + value: 3, + parent: RefCell::new(Weak::new()), + children: RefCell::new(vec![]), + }); + + println!( + "leaf strong = {}, weak = {}", + Rc::strong_count(&leaf), + Rc::weak_count(&leaf), + ); + + { + let branch = Rc::new(Node { + value: 5, + parent: RefCell::new(Weak::new()), + children: RefCell::new(vec![Rc::clone(&leaf)]), + }); + + *leaf.parent.borrow_mut() = Rc::downgrade(&branch); + + println!( + "branch strong = {}, weak = {}", + Rc::strong_count(&branch), + Rc::weak_count(&branch), + ); + + println!( + "leaf strong = {}, weak = {}", + Rc::strong_count(&leaf), + Rc::weak_count(&leaf), + ); + } + + println!("leaf parent = {:?}", leaf.parent.borrow().upgrade()); + println!( + "leaf strong = {}, weak = {}", + Rc::strong_count(&leaf), + Rc::weak_count(&leaf), + ); +}
Phantom Type
+虚类型/幽灵类型参数是一种在运行时不出现, +仅进行静态编译检查的类型参数.
++#![allow(unused)] +fn main() { +use std::marker::PhantomData; + +struct Iter<'a, T: 'a> { + ptr: *const T, + end: *const T, + _marker: PhantomData<&'a T>, +} + +struct Vec<T> { + data: *const T, + len: usize, + cap: usize, + _marker: PhantomData<T>, +} +}
+use std::marker::PhantomData; + +#[derive(PartialEq)] +struct PhantomTuple<A, B>(A, PhantomData<B>); + +#[derive(PartialEq)] +struct PhantomStruct<A, B> { first: A, phantom: PhantomData<B> } + +fn main() { + let _tuple1: PhantomTuple<char, f32> = PhantomTuple('Q', PhantomData); + let _tuple2: PhantomTuple<char, f64> = PhantomTuple('Q', PhantomData); + + let _struct1: PhantomStruct<char, f32> = PhantomStruct { + first: 'Q', + phantom: PhantomData, + }; + let _struct2: PhantomStruct<char, f64> = PhantomStruct { + first: 'Q', + phantom: PhantomData, + }; + + // 编译期错误！类型不匹配，所以这些值不能够比较： + println!("_tuple1 == _tuple2 yields: {}", + _tuple1 == _tuple2); + + // 编译期错误！类型不匹配，所以这些值不能够比较： + println!("_struct1 == _struct2 yields: {}", + _struct1 == _struct2); +}
+use std::ops::Add; +use std::marker::PhantomData; + +#[derive(Debug, Clone, Copy)] +enum Inch {} +#[derive(Debug, Clone, Copy)] +enum Mm {} + +#[derive(Debug, Clone, Copy)] +struct Length<Unit>(f64, PhantomData<Unit>); + +impl<Unit> Add for Length<Unit> { + type Output = Length<Unit>; + + fn add(self, rhs: Length<Unit>) -> Length<Unit> { + Length(self.0 + rhs.0, PhantomData) + } +} + +fn main() { + let one_foot: Length<Inch> = Length(12.0, PhantomData); + let one_meter: Length<Mm> = Length(1000.0, PhantomData); + + let two_feet = one_foot + one_foot; + let two_meters = one_meter + one_meter; + + println!("one foot + one_foot = {:?} in", two_feet.0); + println!("one meter + one_meter = {:?} mm", two_meters.0); + + // 编译期错误: 类型不匹配. + let compile_error = one_foot + one_meter; +}
Concurrent Programming
+Concurrency Programming Model
+| Name | Pros | Cons |
|---|---|---|
| OS Thread | simple, native model | consistent and context switch overhead |
| Event Driven | perf model | non-liner logic, callback hell |
| Coroutines | perf model | non-system abstraction |
| Actor | distributed model | complex flow control and retry logic |
| Async/Await | perf, native model | complex internal logic |
OS Threads for CPU intensive task (parallel computing),
+Async/Await for I/O intensive task (blocking I/O).
Threads
++use std::thread; +use std::time::Duration; + +fn main() { + let handle = thread::spawn(|| { + for i in 1..5 { + println!("hi number {} from the spawned thread!", i); + thread::sleep(Duration::from_millis(1)); + } + }); + + for i in 1..5 { + println!("hi number {} from the main thread!", i); + thread::sleep(Duration::from_millis(1)); + } + + handle.join().unwrap(); +}
Barrier
++use std::sync::{Arc, Barrier}; +use std::thread; + +fn main() { + let mut handles = Vec::with_capacity(6); + let barrier = Arc::new(Barrier::new(6)); + + for _ in 0..6 { + let b = barrier.clone(); + handles.push(thread::spawn(move|| { + println!("before wait"); + b.wait(); + println!("after wait"); + })); + } + + for handle in handles { + handle.join().unwrap(); + } +}
Condition Variables and Mutex
++use std::thread; +use std::sync::{Arc, Mutex, Condvar}; + +fn main() { + let pair = Arc::new((Mutex::new(false), Condvar::new())); + let pair2 = pair.clone(); + + thread::spawn(move|| { + let &(ref lock, ref cvar) = &*pair2; + let mut started = lock.lock().unwrap(); + println!("changing started"); + *started = true; + cvar.notify_one(); + }); + + let &(ref lock, ref cvar) = &*pair; + let mut started = lock.lock().unwrap(); + while !*started { + started = cvar.wait(started).unwrap(); + } + + println!("started changed"); +}
+use std::sync::{Arc, Mutex}; +use std::thread; + +fn main() { + let counter = Arc::new(Mutex::new(0)); + let mut handles = vec![]; + + for _ in 0..10 { + let counter = Arc::clone(&counter); + let handle = thread::spawn(move || { + let mut num = counter.lock().unwrap(); + *num += 1; + }); + handles.push(handle); + } + + for handle in handles { + handle.join().unwrap(); + } + + println!("Result: {}", *counter.lock().unwrap()); +}
Read and write mutex:
+-
+
- 同时允许多个读, 但最多只能有一个写. +
- 读和写不能同时存在. +
- 可以使用
read/try_read/write/try_write.
+
+use std::sync::RwLock; + +fn main() { + let lock = RwLock::new(5); + + // 同一时间允许多个读. + { + let r1 = lock.read().unwrap(); + let r2 = lock.read().unwrap(); + assert_eq!(*r1, 5); + assert_eq!(*r2, 5); + } // Drop. + + // 同一时间只允许一个写. + { + let mut w = lock.write().unwrap(); + *w += 1; + assert_eq!(*w, 6); + } // Drop. +}
Threads Communication
+Message channel:
++use std::sync::mpsc; +use std::thread; + +fn main() { + let (tx, rx) = mpsc::channel(); + + thread::spawn(move || { + tx.send(1).unwrap(); + }); + + // Block. + println!("receive {}", rx.recv().unwrap()); +}
Sync channel with message buffer:
++use std::sync::mpsc; +use std::thread; +use std::time::Duration; + +fn main() { + // Sync channel with 3 length buffer. + let (tx, rx)= mpsc::sync_channel(3); + + let handle = thread::spawn(move || { + println!("发送之前"); + tx.send(1).unwrap(); + println!("发送之后"); + }); + + println!("睡眠之前"); + thread::sleep(Duration::from_secs(3)); + println!("睡眠之后"); + + println!("receive {}", rx.recv().unwrap()); + handle.join().unwrap(); +}
Send message via for loop:
+use std::sync::mpsc; +use std::thread; +use std::time::Duration; + +fn main() { + let (tx, rx) = mpsc::channel(); + + thread::spawn(move || { + let values = vec![ + String::from("hi"), + String::from("from"), + String::from("the"), + String::from("thread"), + ]; + + for value in values { + tx.send(value).unwrap(); + thread::sleep(Duration::from_secs(1)); + } + }); + + for received in rx { + println!("Got: {}", received); + } +}
Multiple producers:
++use std::sync::mpsc; +use std::thread; + +fn main() { + let (tx, rx) = mpsc::channel(); + let tx1 = tx.clone(); + + thread::spawn(move || { + tx.send(String::from("hi from raw tx")).unwrap(); + }); + + thread::spawn(move || { + tx1.send(String::from("hi from cloned tx")).unwrap(); + }); + + for received in rx { + println!("Got: {}", received); + } +}
Multiple type message:
++use std::sync::mpsc::{self, Receiver, Sender}; + +enum Fruit { + Apple(u8), + Orange(String) +} + +fn main() { + let (tx, rx): (Sender<Fruit>, Receiver<Fruit>) = mpsc::channel(); + + tx.send(Fruit::Orange("sweet".to_string())).unwrap(); + tx.send(Fruit::Apple(2)).unwrap(); + + for _ in 0..2 { + match rx.recv().unwrap() { + Fruit::Apple(count) => println!("received {} apples", count), + Fruit::Orange(flavor) => println!("received {} oranges", flavor), + } + } +}
Tokio Semaphore
++use std::sync::Arc; +use tokio::sync::Semaphore; + +#[tokio::main] +async fn main() { + let semaphore = Arc::new(Semaphore::new(3)); + let mut join_handles = Vec::new(); + + for _ in 0..5 { + let permit = semaphore.clone().acquire_owned().await.unwrap(); + join_handles.push(tokio::spawn(async move { + /** + * Task here ... + */ + drop(permit); + })); + } + + for handle in join_handles { + handle.await.unwrap(); + } +}
Atomic Primitives
++use std::ops::Sub; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::thread::{self, JoinHandle}; +use std::time::Instant; + +const N_TIMES: u64 = 10000000; +const N_THREADS: usize = 10; + +static R: AtomicU64 = AtomicU64::new(0); + +fn add_n_times(n: u64) -> JoinHandle<()> { + thread::spawn(move || { + for _ in 0..n { + R.fetch_add(1, Ordering::Relaxed); + } + }) +} + +fn main() { + let s = Instant::now(); + let mut threads = Vec::with_capacity(N_THREADS); + + for _ in 0..N_THREADS { + threads.push(add_n_times(N_TIMES)); + } + + for thread in threads { + thread.join().unwrap(); + } + + assert_eq!(N_TIMES * N_THREADS as u64, R.load(Ordering::Relaxed)); + + println!("{:?}",Instant::now().sub(s)); +}
Ordering 内存顺序:
-
+
- Relaxed: 乱序. +
- Release: 设置内存屏障, 保证它之前的操作永远在它之前. +
- Acquire: 设置内存屏障, 保证它之后的操作永远在它之后. +
- AcqRel: Acquire + Release. +
- SeqCst: 顺序一致性. +
+use std::thread::{self, JoinHandle}; +use std::sync::atomic::{Ordering, AtomicBool}; + +static mut DATA: u64 = 0; +static READY: AtomicBool = AtomicBool::new(false); + +fn reset() { + unsafe { + DATA = 0; + } + READY.store(false, Ordering::Relaxed); +} + +fn producer() -> JoinHandle<()> { + thread::spawn(move || { + unsafe { + DATA = 100; // A + } + READY.store(true, Ordering::Release); // B: 内存屏障 ↑ + }) +} + +fn consumer() -> JoinHandle<()> { + thread::spawn(move || { + while !READY.load(Ordering::Acquire) {} // C: 内存屏障 ↓ + + assert_eq!(100, unsafe { DATA }); // D + }) +} + + +fn main() { + loop { + reset(); + + let t_producer = producer(); + let t_consumer = consumer(); + + t_producer.join().unwrap(); + t_consumer.join().unwrap(); + } +}
Spinlock:
++use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::{hint, thread}; + +fn main() { + let spinlock = Arc::new(AtomicUsize::new(1)); + let spinlock_clone = Arc::clone(&spinlock); + let thread = thread::spawn(move|| { + spinlock_clone.store(0, Ordering::SeqCst); + }); + + // 等待其它线程释放锁. + while spinlock.load(Ordering::SeqCst) != 0 { + hint::spin_loop(); + } + + if let Err(panic) = thread.join() { + println!("Thread had an error: {:?}", panic); + } +}
Send and Sync Trait
+Send and Sync:
+-
+
- Marker trait. +
- 实现
Send的类型可以在线程间安全的传递其所有权, +实现Sync的类型可以在线程间安全的共享 (通过引用). +若&T: Send, 则T: Sync.
+ - 绝大部分类型都实现了
Send/Sync, +例外: 原生指针,Cell/RefCell,Rc.
+
Thread Pool
++#![allow(unused)] +fn main() { +use std::sync::mpsc; +use std::sync::Arc; +use std::sync::Mutex; +use std::thread; + +type Job = Box<dyn FnOnce() + Send + 'static>; + +enum Message { + NewJob(Job), + Terminate, +} + +pub struct ThreadPool { + workers: Vec<Worker>, + sender: mpsc::Sender<Message>, +} + + +impl ThreadPool { + /// Create a new ThreadPool. + /// + /// The size is the number of threads in the pool. + /// + /// # Panics + /// + /// The `new` function will panic if the size is zero. + pub fn new(size: usize) -> ThreadPool { + assert!(size > 0); + + let (sender, receiver) = mpsc::channel(); + let receiver = Arc::new(Mutex::new(receiver)); + let mut workers = Vec::with_capacity(size); + + for id in 0..size { + workers.push(Worker::new(id, Arc::clone(&receiver))); + } + + ThreadPool { workers, sender } + } + + pub fn execute<F>(&self, f: F) + where + F: FnOnce() + Send + 'static, + { + let job = Box::new(f); + self.sender.send(Message::NewJob(job)).unwrap(); + } +} + +impl Drop for ThreadPool { + fn drop(&mut self) { + println!("Sending terminate message to all workers."); + + for _ in &self.workers { + self.sender.send(Message::Terminate).unwrap(); + } + + println!("Shutting down all workers."); + + for worker in &mut self.workers { + println!("Shutting down worker {}", worker.id); + + if let Some(thread) = worker.thread.take() { + thread.join().unwrap(); + } + } + } +} + +struct Worker { + id: usize, + thread: Option<thread::JoinHandle<()>>, +} + +impl Worker { + fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Message>>>) -> Worker { + let thread = thread::spawn(move || loop { + let message = receiver.lock().unwrap().recv().unwrap(); + + match message { + Message::NewJob(job) => { + println!("Worker {} got a job; executing.", id); + job(); + } + Message::Terminate => { + println!("Worker {} was told to terminate.", id); + break; + } + } + }); + + Worker { + id, + thread: Some(thread), + } + } +} +}
Asynchronous Programming
+Async and Await
+-
+
- 在
.await执行期间, 任务可能会在线程间转移.
+ .await只能用于 async fn 函数中.
+
+use futures::executor::block_on; +use futures::join; + +async fn learn_song() -> Song { /* ... */ } +async fn sing_song(song: Song) { /* ... */ } +async fn dance() { /* ... */ } + +async fn learn_and_sing() { + let song = learn_song().await; + sing_song(song).await; +} + +async fn async_main() { + let f1 = learn_and_sing(); + let f2 = dance(); + join!(f1, f2); +} + +fn main() { + block_on(async_main()); +}
+use futures::future; +use futures::select; + +pub fn main() { + let mut a_fut = future::ready(4); + let mut b_fut = future::ready(6); + let mut total = 0; + + loop { + select! { + a = a_fut => total += a, + b = b_fut => total += b, + complete => break, + default => panic!(), // 该分支永远不会运行. + }; + } + + assert_eq!(total, 10); +}
Future Trait
+-
+
Future代表一组计算, 惰性求值. 当.await调用时才真正开始执行.
+Future启动后会因资源等原因阻塞, 转入pending状态.
+Future阻塞后, 当资源准备好可以重新启动时, 会通过Waker.wake通知执行器, 等待被下一次poll.
+
+#![allow(unused)] +fn main() { +trait Future { + type Output; + fn poll( + self: Pin<&mut Self>, + cx: &mut Context<'_>, + ) -> Poll<Self::Output>; +} +}
+#![allow(unused)] + +fn main() { +use std::{ + future::Future, + pin::Pin, + sync::{Arc, Mutex}, + task::{Context, Poll, Waker}, + thread, + time::Duration, +}; + +pub struct TimerFuture { + shared_state: Arc<Mutex<SharedState>>, +} + +struct SharedState { + completed: bool, + waker: Option<Waker>, +} + +impl Future for TimerFuture { + type Output = (); + fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { + let mut shared_state = self.shared_state.lock().unwrap(); + + if shared_state.completed { + Poll::Ready(()) + } else { + shared_state.waker = Some(cx.waker().clone()); + Poll::Pending + } + } +} + +impl TimerFuture { + pub fn new(duration: Duration) -> Self { + let shared_state = Arc::new(Mutex::new(SharedState { + completed: false, + waker: None, + })); + + let thread_shared_state = shared_state.clone(); + + thread::spawn(move || { + thread::sleep(duration); + let mut shared_state = thread_shared_state.lock().unwrap(); + shared_state.completed = true; + if let Some(waker) = shared_state.waker.take() { + waker.wake() + } + }); + + TimerFuture { shared_state } + } +} +}
当 Future 会返回 Poll::Pending 时,
+一定要确保 wake 能被正常调用,
+否则会导致任务永远被挂起,
+再也不会被执行器 poll.
+use std::future::Future; +use std::pin::Pin; +use std::task::{Context, Poll}; +use std::time::{Duration, Instant}; + +struct Delay { + when: Instant, +} + +impl Future for Delay { + type Output = &'static str; + + fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) + -> Poll<&'static str> + { + if Instant::now() >= self.when { + println!("Hello world"); + Poll::Ready("done") + } else { + let waker = cx.waker().clone(); + let when = self.when; + + thread::spawn(move || { + let now = Instant::now(); + + if now < when { + thread::sleep(when - now); + } + + waker.wake(); + }); + + Poll::Pending + } + } +} + +#[tokio::main] +async fn main() { + let when = Instant::now() + Duration::from_millis(10); + let future = Delay { when }; + + let out = future.await; + assert_eq!(out, "done"); +}
Asynchronous Runtime
++use { + futures::{ + future::{BoxFuture, FutureExt}, + task::{waker_ref, ArcWake}, + }, + std::{ + future::Future, + sync::mpsc::{sync_channel, Receiver, SyncSender}, + sync::{Arc, Mutex}, + task::{Context, Poll}, + time::Duration, + }, + // 引入之前实现的定时器模块 + timer_future::TimerFuture, +}; + +struct Task { + future: Mutex<Option<BoxFuture<'static, ()>>>, + task_sender: SyncSender<Arc<Task>>, +} + +impl ArcWake for Task { + fn wake_by_ref(arc_self: &Arc<Self>) { + let cloned = arc_self.clone(); + arc_self + .task_sender + .send(cloned) + .expect("任务队列已满"); + } +} + +#[derive(Clone)] +struct Spawner { + task_sender: SyncSender<Arc<Task>>, +} + +impl Spawner { + fn spawn(&self, future: impl Future<Output = ()> + 'static + Send) { + let future = future.boxed(); + let task = Arc::new(Task { + future: Mutex::new(Some(future)), + task_sender: self.task_sender.clone(), + }); + self.task_sender.send(task).expect("任务队列已满"); + } +} + +struct Executor { + ready_queue: Receiver<Arc<Task>>, +} + +impl Executor { + fn run(&self) { + while let Ok(task) = self.ready_queue.recv() { + let mut future_slot = task.future.lock().unwrap(); + + if let Some(mut future) = future_slot.take() { + let waker = waker_ref(&task); + let context = &mut Context::from_waker(&*waker); + + if future.as_mut().poll(context).is_pending() { + // Future 未执行完，, 将它放回任务中, 等待下次被 poll. + *future_slot = Some(future); + } + } + } + } +} + +fn new_executor_and_spawner() -> (Executor, Spawner) { + const MAX_QUEUED_TASKS: usize = 10_000; + let (task_sender, ready_queue) = sync_channel(MAX_QUEUED_TASKS); + (Executor { ready_queue }, Spawner { task_sender }) +} + +fn main() { + let (executor, spawner) = new_executor_and_spawner(); + + spawner.spawn(async { + println!("howdy!"); + TimerFuture::new(Duration::new(2, 0)).await; + println!("done!"); + }); + + drop(spawner); + + // 运行执行器直到任务队列为空. + // 任务运行后, 会先打印 `howdy!`, 暂停 2 秒, 接着打印 `done!`. + executor.run(); +}
+use std::cell::RefCell; +use std::future::Future; +use std::pin::Pin; +use std::sync::{Arc, Mutex}; +use std::task::{Context, Poll, Waker}; +use std::thread; +use std::time::{Duration, Instant}; +use futures::task::{self, ArcWake}; +use crossbeam::channel; + +fn main() { + let mini_tokio = MiniTokio::new(); + + mini_tokio.spawn(async { + spawn(async { + delay(Duration::from_millis(100)).await; + println!("world"); + }); + + spawn(async { + println!("hello"); + }); + + delay(Duration::from_millis(200)).await; + std::process::exit(0); + }); + + mini_tokio.run(); +} + +struct MiniTokio { + scheduled: channel::Receiver<Arc<Task>>, + sender: channel::Sender<Arc<Task>>, +} + +impl MiniTokio { + fn new() -> MiniTokio { + let (sender, scheduled) = channel::unbounded(); + + MiniTokio { scheduled, sender } + } + + fn spawn<F>(&self, future: F) + where + F: Future<Output = ()> + Send + 'static, + { + Task::spawn(future, &self.sender); + } + + fn run(&self) { + CURRENT.with(|cell| { + *cell.borrow_mut() = Some(self.sender.clone()); + }); + + while let Ok(task) = self.scheduled.recv() { + task.poll(); + } + } +} + +pub fn spawn<F>(future: F) +where + F: Future<Output = ()> + Send + 'static, +{ + CURRENT.with(|cell| { + let borrow = cell.borrow(); + let sender = borrow.as_ref().unwrap(); + Task::spawn(future, sender); + }); +} + +async fn delay(dur: Duration) { + struct Delay { + when: Instant, + waker: Option<Arc<Mutex<Waker>>>, + } + + impl Future for Delay { + type Output = (); + + fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> { + if let Some(waker) = &self.waker { + let mut waker = waker.lock().unwrap(); + + if !waker.will_wake(cx.waker()) { + *waker = cx.waker().clone(); + } + } else { + let when = self.when; + let waker = Arc::new(Mutex::new(cx.waker().clone())); + self.waker = Some(waker.clone()); + + thread::spawn(move || { + let now = Instant::now(); + + if now < when { + thread::sleep(when - now); + } + + let waker = waker.lock().unwrap(); + waker.wake_by_ref(); + }); + } + + if Instant::now() >= self.when { + Poll::Ready(()) + } else { + Poll::Pending + } + } + } + + let future = Delay { + when: Instant::now() + dur, + waker: None, + }; + + future.await; +} + +thread_local! { + static CURRENT: RefCell<Option<channel::Sender<Arc<Task>>>> = + RefCell::new(None); +} + +struct Task { + future: Mutex<Pin<Box<dyn Future<Output = ()> + Send>>>, + executor: channel::Sender<Arc<Task>>, +} + +impl Task { + fn spawn<F>(future: F, sender: &channel::Sender<Arc<Task>>) + where + F: Future<Output = ()> + Send + 'static, + { + let task = Arc::new(Task { + future: Mutex::new(Box::pin(future)), + executor: sender.clone(), + }); + + let _ = sender.send(task); + } + + fn poll(self: Arc<Self>) { + let waker = task::waker(self.clone()); + let mut cx = Context::from_waker(&waker); + let mut future = self.future.try_lock().unwrap(); + let _ = future.as_mut().poll(&mut cx); + } +} + +impl ArcWake for Task { + fn wake_by_ref(arc_self: &Arc<Self>) { + let _ = arc_self.executor.send(arc_self.clone()); + } +}
+#[tokio::main] +async fn main() { + println!("Hello world"); +} + +fn main() { + tokio::runtime::Builder::new_multi_thread() + .enable_all() + .build() + .unwrap() + .block_on(async { + println!("Hello world"); + }) +}
Tests
++#![allow(unused)] +fn main() { +fn greeting(name: &str) -> String { + format!("Hello {}!", name) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + #[ignore] + #[should_panic] + #[should_panic(expected = "Panic message.")] + fn greeting_contains_name() { + let target = "name"; + let result = greeting("Name"); + assert!( + result.contains(target), + "Expect: `{}`, Result: `{}`", + target, + result + ); + } +} +}
IO
+Path
++use std::path::Path; + +fn main() { + let path = Path::new("."); + let new_path = path.join("a").join("b"); + + // 将路径转换成一个字符串切片 + match new_path.to_str() { + None => panic!("new path is not a valid UTF-8 sequence"), + Some(s) => println!("new path is {}", s), + } + + // `display` 方法返回一个可显示的结构体 + let display = path.display(); +}
Files
+-
+
File::open.
+File::create.
+file.read_to_string.
+file.write_all.
+bufReader.lines.
+OpenOptions.
+fs::read_dir.
+fs::create_dir.
+fs::create_dir_all.
+fs::remove_file.
+fs::remove_dir.
+fs::symlink.
+
+use std::error::Error; +use std::fs::File; +use std::io::prelude::*; +use std::path::Path; + +fn main() { + let path = Path::new("hello.txt"); + let display = path.display(); + + let mut file = match File::open(&path) { + Err(why) => panic!("couldn't open {}: {}", display, + why.description()), + Ok(file) => file, + }; + + let mut s = String::new(); + match file.read_to_string(&mut s) { + Err(why) => panic!("couldn't read {}: {}", display, + why.description()), + Ok(_) => print!("{} contains:\n{}", display, s), + } +}
+use std::fs::File; +use std::io::{self, BufRead}; +use std::path::Path; + +fn main() { + if let Ok(lines) = read_lines("./hosts") { + for line in lines { + if let Ok(ip) = line { + println!("{}", ip); + } + } + } +} + +fn read_lines<P>(filename: P) -> io::Result<io::Lines<io::BufReader<File>>> +where P: AsRef<Path>, { + let file = File::open(filename)?; + Ok(io::BufReader::new(file).lines()) +}
+static LOREM_IPSUM: &'static str = "Words"; + +use std::error::Error; +use std::fs::File; +use std::io::prelude::*; +use std::path::Path; + +fn main() { + let path = Path::new("out/lorem_ipsum.txt"); + let display = path.display(); + + let mut file = match File::create(&path) { + Err(why) => panic!("couldn't create {}: {}", + display, + why.description()), + Ok(file) => file, + }; + + match file.write_all(LOREM_IPSUM.as_bytes()) { + Err(why) => { + panic!("couldn't write to {}: {}", display, + why.description()) + }, + Ok(_) => println!("successfully wrote to {}", display), + } +}
+use std::fs; +use std::fs::{File, OpenOptions}; +use std::io; +use std::io::prelude::*; +use std::os::unix; +use std::path::Path; + +fn cat(path: &Path) -> io::Result<String> { + let mut f = File::open(path)?; + let mut s = String::new(); + match f.read_to_string(&mut s) { + Ok(_) => Ok(s), + Err(e) => Err(e), + } +} + +fn echo(s: &str, path: &Path) -> io::Result<()> { + let mut f = File::create(path)?; + f.write_all(s.as_bytes()) +} + +fn touch(path: &Path) -> io::Result<()> { + match OpenOptions::new().create(true).write(true).open(path) { + Ok(_) => Ok(()), + Err(e) => Err(e), + } +} + +fn main() { + println!("`mkdir a`"); + match fs::create_dir("a") { + Err(why) => println!("! {:?}", why.kind()), + Ok(_) => {}, + } + + println!("`echo hello > a/b.txt`"); + echo("hello", &Path::new("a/b.txt")).unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + + println!("`mkdir -p a/c/d`"); + fs::create_dir_all("a/c/d").unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + + println!("`touch a/c/e.txt`"); + touch(&Path::new("a/c/e.txt")).unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + + println!("`ln -s ../b.txt a/c/b.txt`"); + if cfg!(target_family = "unix") { + unix::fs::symlink("../b.txt", "a/c/b.txt").unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + } + + println!("`cat a/c/b.txt`"); + match cat(&Path::new("a/c/b.txt")) { + Err(why) => println!("! {:?}", why.kind()), + Ok(s) => println!("> {}", s), + } + + println!("`ls a`"); + match fs::read_dir("a") { + Err(why) => println!("! {:?}", why.kind()), + Ok(paths) => for path in paths { + println!("> {:?}", path.unwrap().path()); + }, + } + + println!("`rm a/c/e.txt`"); + fs::remove_file("a/c/e.txt").unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); + + println!("`rmdir a/c/d`"); + fs::remove_dir("a/c/d").unwrap_or_else(|why| { + println!("! {:?}", why.kind()); + }); +}
System
+Process
++use std::process::Command; + +fn main() { + let output = Command::new("rustc") + .arg("--version") + .output().unwrap_or_else(|e| { + panic!("failed to execute process: {}", e) + }); + + if output.status.success() { + let s = String::from_utf8_lossy(&output.stdout); + print!("rustc succeeded and stdout was:\n{}", s); + } else { + let s = String::from_utf8_lossy(&output.stderr); + print!("rustc failed and stderr was:\n{}", s); + } +}
+use std::error::Error; +use std::io::prelude::*; +use std::process::{Command, Stdio}; + +static PROGRAM: &'static str = +"the quick brown fox jumped over the lazy dog\n"; + +fn main() { + let process = match Command::new("wc") + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .spawn() { + Err(why) => panic!("couldn't spawn wc: {}", why.description()), + Ok(process) => process, + }; + + match process.stdin.unwrap().write_all(PROGRAM.as_bytes()) { + Err(why) => panic!("couldn't write to wc stdin: {}", + why.description()), + Ok(_) => println!("sent program to wc"), + } + + let mut s = String::new(); + match process.stdout.unwrap().read_to_string(&mut s) { + Err(why) => panic!("couldn't read wc stdout: {}", + why.description()), + Ok(_) => print!("wc responded with:\n{}", s), + } +}
Command Line
+++use std::env; +use std::error::Error; +use std::fs; +use std::process; + +pub struct Config { + pub query: String, + pub filename: String, + pub case_sensitive: bool, +} + +impl Config { + pub fn new(args: &[String]) -> Result<Config, &'static str> { + if args.len() < 3 { + return Err("not enough arguments"); + } + + let query = args[1].clone(); + let filename = args[2].clone(); + + let case_sensitive = env::var("CASE_INSENSITIVE").is_err(); + + Ok(Config { + query, + filename, + case_sensitive, + }) + } +} + +pub fn run(config: Config) -> Result<(), Box<dyn Error>> { + let contents = fs::read_to_string(config.filename)?; + + let results = if config.case_sensitive { + search(&config.query, &contents) + } else { + search_case_insensitive(&config.query, &contents) + }; + + for line in results { + println!("{}", line); + } + + Ok(()) +} + +pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { + let mut results = Vec::new(); + + for line in contents.lines() { + if line.contains(query) { + results.push(line); + } + } + + results +} + +pub fn search_case_insensitive<'a>( + query: &str, + contents: &'a str, +) -> Vec<&'a str> { + let query = query.to_lowercase(); + let mut results = Vec::new(); + + for line in contents.lines() { + if line.to_lowercase().contains(&query) { + results.push(line); + } + } + + results +} + +fn main() { + let args: Vec<String> = env::args().collect(); + + let config = Config::new(&args).unwrap_or_else(|err| { + eprintln!("Problem parsing arguments: {}", err); + process::exit(1); + }); + + if let Err(e) = run(config) { + eprintln!("Application error: {}", e); + + process::exit(1); + } +}
Macros
++#![allow(unused)] +fn main() { +#[macro_export] +macro_rules! vec { + ( $( $x:expr ),* ) => { + { + let mut temp_vec = Vec::new(); + $( + temp_vec.push($x); + )* + temp_vec + } + }; +} +}
Unsafe Code
+unsafe {}:
-
+
- 对原始指针进行解引用. +
- 调用
不安全的函数 (包括 C 函数, 编译器内建指令, 原始分配器).
+ - 实现
不安全的特性.
+ - 访问
union字段.
+ - 改变静态数据. +
Comments
++#![allow(unused)] +fn main() { +// Line Comments +/* Block Comments */ +/// Document Line Comments +/** Document Block Comments */ +//! Crate Line Comments +/*! Crate Block Comments */ + +/// [`Option`] +/// [`Type`](struct@Type) +/// [`Type`](fn@Type) + +#[doc(alias = "alias" )] +}
Attributes
+-
+
- Crate scope:
#![crate_attribute].
+ - Module/Function scope:
#[item_attribute].
+
+#![allow(unused)] +fn main() { +#[attribute = "value"] +#[attribute(key = "value")] +#[attribute(value)] +}
Crate Attributes
++#![allow(unused)] +#![crate_type = "lib"] +#![crate_name = "rand"] +fn main() { +}
Linter Attributes
++#![allow(unused)] +fn main() { +#[allow(dead_code)] +#[allow(unused)] +}
Compile Attributes
++#[cfg(target_os = "linux")] +fn are_you_on_linux() { + println!("You are running linux!") +} + +#[cfg(not(target_os = "linux"))] +fn are_you_on_linux() { + println!("You are *not* running linux!") +} + +fn main() { + are_you_on_linux(); + + if cfg!(target_os = "linux") { + println!("Yes. It's definitely linux!"); + } else { + println!("Yes. It's definitely *not* linux!"); + } +}
Standard Library
+-
+
as_:borrowed->borrowed.
+into_:owned->owned(移除所有权).
+to_: +borrowed->borrowed, +borrowed->ownedon non-copy types, +owned->ownedon copy types.
+try_: 尝试一次, 失败则返回或报错.
+_mut: 可变借用.
+
Web Development
+Node.js Bindings
+Tasks suite for native Node.js add-ons:
-
+
- Computing intensive tasks with simple I/O:
+e.g
@node-rs/crc32(CPU SIMD instruction),@node-rs/bcrypt,@node-rs/jieba.
+ - System call tasks: +SIMD instruction, GPU instruction. +
Napi:
+Framework for building compiled Node.js add-ons in Rust via Node API.
+#![allow(unused)] +fn main() { +#[macro_use] +extern crate napi; + +/// import the preludes +use napi::bindgen_prelude::*; + +/// module registration is done by the runtime, no need to explicitly do it now. +#[napi] +fn fibonacci(n: u32) -> u32 { + match n { + 1 | 2 => 1, + _ => fibonacci(n - 1) + fibonacci(n - 2), + } +} + +/// use `Fn`, `FnMut` or `FnOnce` traits to defined JavaScript callbacks +/// the return type of callbacks can only be `Result`. +#[napi] +fn get_cwd<T: Fn(String) -> Result<()>>(callback: T) { + callback(env::current_dir().unwrap().to_string_lossy().to_string()).unwrap(); +} + +/// or, define the callback signature in where clause +#[napi] +fn test_callback<T>(callback: T) +where T: Fn(String) -> Result<()> +{} + +/// async fn, require `async` feature enabled. +/// [dependencies] +/// napi = {version="2", features=["async"]} +#[napi] +async fn read_file_async(path: String) -> Result<Buffer> { + tokio::fs::read(path) + .map(|r| match r { + Ok(content) => Ok(content.into()), + Err(e) => Err(Error::new( + Status::GenericFailure, + format!("failed to read file, {}", e), + )), + }) + .await +} +}
Neon:
+Rust bindings for safe and fast native Node.js modules.
+use neon::context::{Context, ModuleContext, FunctionContext}; +use neon::types::JsNumber; +use neon::result::JsResult; +use neon::result::NeonResult; + +fn fibonacci(n: i32) -> i32 { + return match n { + n if n < 1 => 0, + n if n <= 2 => 1, + _ => fibonacci(n - 1) + fibonacci(n - 2) + } +} + +fn fibonacci_api(mut cx: FunctionContext) -> JsResult<JsNumber> { + let handle = cx.argument::<JsNumber>(0).unwrap(); + let res = fibonacci(handle.value(&mut cx) as i32); + Ok(cx.number(res)) +} + +#[neon::main] +fn main(mut cx: ModuleContext) -> NeonResult<()> { + cx.export_function("fibonacci_rs", fibonacci_api)?; + Ok(()) +}
const { fibonacci_rs } = require('./index.node');
+
+const value = process.argv[2] || null;
+const number = parseInt(value);
+
+if (isNaN(number)) {
+ console.log('Provided value is not a number');
+ return;
+}
+
+const result = fibonacci_rs(number);
+console.log(result);
+Library
+-
+
- Num: Numeric Types and Traits +
- Rand: Random Number Generator +
- Regex: Regular Expression Engine +
- Chrono: DateTime Library +
- AsyncStd: Asynchronous Version Standard Library +
- Crossbeam: Concurrent Programming Tools +
- Tokio: Asynchronous Runtime +
- Rayon: Data Parallelism Library +
- Log: Logging Library +
- Tracing: Tracing Library +
- Serde: Serialization Framework +
- Axum: Tokio Web Framework +
- Rocket: Web Framework +
- Actix: Web Framework +
- Warp: Web Framework +
- Request: HTTP Client +
- Quiche: QUIC and HTTP/3 Library +
- Tonic: gPRC Framework +
- QuickWit: Distributed Search Engine +
- MeiliSearch: Realtime Search Engine +
- Clap: CLI Framework +
- Console: ProgressBar +
- Syn: Source Code Parser +
- Napi: Node.js Bindings Library: +
- Neon: Node.js Bindings Library: +
- Git: Git Bindings Library +
- PrettyAssertions +
- Criterion: Benchmarking Library +
- Clog: Conventional Changelog +
Reference
+ + +- ), Nil,\n}","breadcrumbs":"Rust Basic Notes » Box Type","id":"70","title":"Box Type"},"71":{"body":"&smart_pointer => smart_pointer.defer(). *smart_pointer => *(smart_pointer.defer()). smart_pointer.method() => (&smart_pointer).method() => (smart_pointer.defer()).method(). When T: Deref