2021-01-01 11:28:10 +00:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js rust" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > Collections Are Smart Pointers - Rust Design Patterns< / title >
2021-08-25 02:58:29 +00:00
2021-01-01 11:28:10 +00:00
<!-- Custom HTML head -->
< meta content = "text/html; charset=utf-8" http-equiv = "Content-Type" >
< meta name = "description" content = "A catalogue of Rust design patterns, anti-patterns and idioms" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
2021-08-25 02:58:29 +00:00
< link rel = "icon" href = "../favicon.svg" >
< link rel = "shortcut icon" href = "../favicon.png" >
< link rel = "stylesheet" href = "../css/variables.css" >
2021-01-01 11:28:10 +00:00
< link rel = "stylesheet" href = "../css/general.css" >
< link rel = "stylesheet" href = "../css/chrome.css" >
2021-08-25 02:58:29 +00:00
< link rel = "stylesheet" href = "../css/print.css" media = "print" >
2021-01-01 11:28:10 +00:00
<!-- Fonts -->
< link rel = "stylesheet" href = "../FontAwesome/css/font-awesome.css" >
2021-08-25 02:58:29 +00:00
< link rel = "stylesheet" href = "../fonts/fonts.css" >
2021-01-01 11:28:10 +00:00
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" href = "../highlight.css" >
< link rel = "stylesheet" href = "../tomorrow-night.css" >
< link rel = "stylesheet" href = "../ayu-highlight.css" >
<!-- Custom theme stylesheets -->
2021-08-25 02:58:29 +00:00
< / head >
2021-01-01 11:28:10 +00:00
< body >
<!-- Provide site root to javascript -->
< script type = "text/javascript" >
var path_to_root = "../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "rust";
< / script >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script type = "text/javascript" >
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script type = "text/javascript" >
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('rust')
html.classList.add(theme);
html.classList.add('js');
< / script >
<!-- Hide / unhide sidebar before it is displayed -->
< script type = "text/javascript" >
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
< div class = "sidebar-scrollbox" >
2021-08-25 02:58:29 +00:00
< ol class = "chapter" > < li class = "chapter-item expanded " > < a href = "../intro.html" > < strong aria-hidden = "true" > 1.< / strong > Introduction< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/index.html" > < strong aria-hidden = "true" > 2.< / strong > Idioms< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../idioms/coercion-arguments.html" > < strong aria-hidden = "true" > 2.1.< / strong > Use borrowed types for arguments< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/concat-format.html" > < strong aria-hidden = "true" > 2.2.< / strong > Concatenating Strings with format!< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/ctor.html" > < strong aria-hidden = "true" > 2.3.< / strong > Constructor< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/default.html" > < strong aria-hidden = "true" > 2.4.< / strong > The Default Trait< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/deref.html" class = "active" > < strong aria-hidden = "true" > 2.5.< / strong > Collections Are Smart Pointers< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/dtor-finally.html" > < strong aria-hidden = "true" > 2.6.< / strong > Finalisation in Destructors< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/mem-replace.html" > < strong aria-hidden = "true" > 2.7.< / strong > mem::{take(), replace()}< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/on-stack-dyn-dispatch.html" > < strong aria-hidden = "true" > 2.8.< / strong > On-Stack Dynamic Dispatch< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/ffi/intro.html" > < strong aria-hidden = "true" > 2.9.< / strong > Foreign function interface (FFI)< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../idioms/ffi/errors.html" > < strong aria-hidden = "true" > 2.9.1.< / strong > Idiomatic Errors< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/ffi/accepting-strings.html" > < strong aria-hidden = "true" > 2.9.2.< / strong > Accepting Strings< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/ffi/passing-strings.html" > < strong aria-hidden = "true" > 2.9.3.< / strong > Passing Strings< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/option-iter.html" > < strong aria-hidden = "true" > 2.10.< / strong > Iterating over an Option< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/pass-var-to-closure.html" > < strong aria-hidden = "true" > 2.11.< / strong > Pass Variables to Closure< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/priv-extend.html" > < strong aria-hidden = "true" > 2.12.< / strong > Privacy For Extensibility< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/rustdoc-init.html" > < strong aria-hidden = "true" > 2.13.< / strong > Easy doc initialization< / a > < / li > < li class = "chapter-item expanded " > < a href = "../idioms/temporary-mutability.html" > < strong aria-hidden = "true" > 2.14.< / strong > Temporary mutability< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../patterns/index.html" > < strong aria-hidden = "true" > 3.< / strong > Design Patterns< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../patterns/behavioural/intro.html" > < strong aria-hidden = "true" > 3.1.< / strong > Behavioural< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../patterns/behavioural/command.html" > < strong aria-hidden = "true" > 3.1.1.< / strong > Command< / a > < / li > < li class = "chapter-item expanded " > < a href = "../patterns/behavioural/interpreter.html" > < strong aria-hidden = "true" > 3.1.2.< / strong > Interpreter< / a > < / li > < li class = "chapter-item expanded " > < a href = "../patterns/behavioural/newtype.html" > < strong aria-hidden = "true" > 3.1.3.< / strong > Newtype< / a > < / li > < li class = "chapter-item expanded " > < a href = "../patterns/behavioural/RAII.html" > < strong aria-hidden = "true" > 3.1.4.< / strong > RAII Guards< / a > < / li > < li class = "chapter-item expanded " > < a href = "../patterns/behavioural/strategy.html" > < strong aria-hidden = "true" > 3.1.5.< / strong > Strategy< / a > < / li > < li class = "chapter-item expanded " > < a href = "../patterns/behavioural/visitor.html" > < strong aria-hidden = "true" > 3.1.6.< / strong > Visitor< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded
2021-01-01 11:28:10 +00:00
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" > < / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky bordered" >
< div class = "left-buttons" >
< button id = "sidebar-toggle" class = "icon-button" type = "button" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / button >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust (default)< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
2021-08-25 02:58:29 +00:00
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search. (Shortkey: s)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "S" aria-controls = "searchbar" >
2021-01-01 11:28:10 +00:00
< i class = "fa fa-search" > < / i >
< / button >
2021-08-25 02:58:29 +00:00
< / div >
2021-01-01 11:28:10 +00:00
< h1 class = "menu-title" > Rust Design Patterns< / h1 >
< div class = "right-buttons" >
2021-08-25 02:58:29 +00:00
< a href = "../print.html" title = "Print this book" aria-label = "Print this book" >
2021-01-01 11:28:10 +00:00
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
2021-08-25 02:58:29 +00:00
< a href = "https://github.com/rust-unofficial/patterns" title = "Git repository" aria-label = "Git repository" >
2021-01-01 11:28:10 +00:00
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
2021-08-25 02:58:29 +00:00
2021-01-01 11:28:10 +00:00
< / div >
< / div >
2021-08-25 02:58:29 +00:00
< div id = "search-wrapper" class = "hidden" >
2021-01-01 11:28:10 +00:00
< form id = "searchbar-outer" class = "searchbar-outer" >
2021-05-14 04:50:28 +00:00
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
2021-01-01 11:28:10 +00:00
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script type = "text/javascript" >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
2021-03-02 21:12:13 +00:00
< h1 id = "collections-are-smart-pointers" > < a class = "header" href = "#collections-are-smart-pointers" > Collections are smart pointers< / a > < / h1 >
< h2 id = "description" > < a class = "header" href = "#description" > Description< / a > < / h2 >
2021-01-01 11:28:10 +00:00
< p > Use the < code > Deref< / code > trait to treat collections like smart pointers, offering owning
and borrowed views of data.< / p >
2021-03-02 21:12:13 +00:00
< h2 id = "example" > < a class = "header" href = "#example" > Example< / a > < / h2 >
2021-01-02 11:41:18 +00:00
< pre > < code class = "language-rust ignore" > use std::ops::Deref;
struct Vec< T> {
2021-07-08 22:47:26 +00:00
data: RawVec< T> ,
2021-01-02 11:41:18 +00:00
//..
2021-01-01 11:28:10 +00:00
}
impl< T> Deref for Vec< T> {
type Target = [T];
fn deref(& self) -> & [T] {
2021-01-02 11:41:18 +00:00
//..
2021-01-01 11:28:10 +00:00
}
}
2021-01-02 11:41:18 +00:00
< / code > < / pre >
2021-01-01 11:28:10 +00:00
< p > A < code > Vec< T> < / code > is an owning collection of < code > T< / code > s, a slice (< code > & [T]< / code > ) is a borrowed
collection of < code > T< / code > s. Implementing < code > Deref< / code > for < code > Vec< / code > allows implicit dereferencing
from < code > & Vec< T> < / code > to < code > & [T]< / code > and includes the relationship in auto-derefencing
searches. Most methods you might expect to be implemented for < code > Vec< / code > s are instead
implemented for slices.< / p >
< p > See also < code > String< / code > and < code > & str< / code > .< / p >
2021-03-02 21:12:13 +00:00
< h2 id = "motivation" > < a class = "header" href = "#motivation" > Motivation< / a > < / h2 >
2021-01-01 11:28:10 +00:00
< p > Ownership and borrowing are key aspects of the Rust language. Data structures
must account for these semantics properly in order to give a good user
experience. When implementing a data structure which owns its data, offering a
borrowed view of that data allows for more flexible APIs.< / p >
2021-03-02 21:12:13 +00:00
< h2 id = "advantages" > < a class = "header" href = "#advantages" > Advantages< / a > < / h2 >
2021-01-01 11:28:10 +00:00
< p > Most methods can be implemented only for the borrowed view, they are then
implicitly available for the owning view.< / p >
< p > Gives clients a choice between borrowing or taking ownership of data.< / p >
2021-03-02 21:12:13 +00:00
< h2 id = "disadvantages" > < a class = "header" href = "#disadvantages" > Disadvantages< / a > < / h2 >
2021-01-01 11:28:10 +00:00
< p > Methods and traits only available via dereferencing are not taken into account
when bounds checking, so generic programming with data structures using this
pattern can get complex (see the < code > Borrow< / code > and < code > AsRef< / code > traits, etc.).< / p >
2021-03-02 21:12:13 +00:00
< h2 id = "discussion" > < a class = "header" href = "#discussion" > Discussion< / a > < / h2 >
2021-01-01 11:28:10 +00:00
< p > Smart pointers and collections are analogous: a smart pointer points to a single
object, whereas a collection points to many objects. From the point of view of
the type system there is little difference between the two. A collection owns
its data if the only way to access each datum is via the collection and the
collection is responsible for deleting the data (even in cases of shared
ownership, some kind of borrowed view may be appropriate). If a collection owns
its data, it is usually useful to provide a view of the data as borrowed so that
2021-10-02 09:52:20 +00:00
it can be referenced multiple times.< / p >
2021-01-01 11:28:10 +00:00
< p > Most smart pointers (e.g., < code > Foo< T> < / code > ) implement < code > Deref< Target=T> < / code > . However,
collections will usually dereference to a custom type. < code > [T]< / code > and < code > str< / code > have some
language support, but in the general case, this is not necessary. < code > Foo< T> < / code > can
implement < code > Deref< Target=Bar< T> > < / code > where < code > Bar< / code > is a dynamically sized type and
< code > & Bar< T> < / code > is a borrowed view of the data in < code > Foo< T> < / code > .< / p >
< p > Commonly, ordered collections will implement < code > Index< / code > for < code > Range< / code > s to provide
slicing syntax. The target will be the borrowed view.< / p >
2021-03-02 21:12:13 +00:00
< h2 id = "see-also" > < a class = "header" href = "#see-also" > See also< / a > < / h2 >
2021-01-01 11:28:10 +00:00
< p > < a href = "../anti_patterns/deref.html" > Deref polymorphism anti-pattern< / a > .< / p >
< p > < a href = "https://doc.rust-lang.org/std/ops/trait.Deref.html" > Documentation for < code > Deref< / code > trait< / a > .< / p >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
2021-08-25 02:58:29 +00:00
< a rel = "prev" href = "../idioms/default.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2021-01-01 11:28:10 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2021-08-25 02:58:29 +00:00
< a rel = "next" href = "../idioms/dtor-finally.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2021-01-01 11:28:10 +00:00
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
2021-08-25 02:58:29 +00:00
< a rel = "prev" href = "../idioms/default.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2021-01-01 11:28:10 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2021-08-25 02:58:29 +00:00
< a rel = "next" href = "../idioms/dtor-finally.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2021-01-01 11:28:10 +00:00
< i class = "fa fa-angle-right" > < / i >
< / a >
2021-08-25 02:58:29 +00:00
< / nav >
2021-01-01 11:28:10 +00:00
< / div >
2021-08-25 02:58:29 +00:00
< script type = "text/javascript" >
2021-01-01 11:28:10 +00:00
window.playground_copyable = true;
< / script >
2021-08-25 02:58:29 +00:00
< script src = "../elasticlunr.min.js" type = "text/javascript" charset = "utf-8" > < / script >
2021-01-01 11:28:10 +00:00
< script src = "../mark.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../searcher.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../clipboard.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../highlight.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../book.js" type = "text/javascript" charset = "utf-8" > < / script >
<!-- Custom JS scripts -->
< / body >
< / html >
