<buttonid="sidebar-toggle"class="icon-button"type="button"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<inputtype="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<p>Every time you write code in Rust, you are writing it in a <code>crate</code>. A <code>crate</code> is the file, or files, that go together for your code. Inside the file you write you can also make a <code>mod</code>. A <code>mod</code> is a space for functions, structs, etc. and is used for a few reasons:</p>
<ul>
<li>Building your code: it helps you think about the general structure of your code. This can be important as your code gets larger and larger.</li>
<li>Reading your code: people can understand your code more easily. For example, the name <code>std::collections::HashMap</code> tells you that it's in <code>std</code> inside the module <code>collections</code>. This gives you a hint that maybe there are more collection types inside <code>collections</code> that you can try.</li>
<li>Privacy: everything starts out as private. That lets you keep users from using functions directly.</li>
</ul>
<p>To make a <code>mod</code>, just write <code>mod</code> and start a code block with <code>{}</code>. We will make a mod called <code>print_things</code> that has some printing-related functions.</p>
<p>You can see that we wrote <code>use std::fmt::Display;</code> inside <code>print_things</code>, because it is a separate space. If you wrote <code>use std::fmt::Display;</code> inside <code>main()</code> it wouldn't help. Also, we can't call it from <code>main()</code> right now. Without the <code>pub</code> keyword in front of <code>fn</code> it will stay private. Let's try to call it without <code>pub</code>. Here's one way to write it:</p>
<p><code>crate</code> means "inside this project", but for our simple example it's the same as "inside this file". Inside that is the mod <code>print_things</code>, then finally the <code>prints_one_thing()</code> function. You can write that every time, or you can write <code>use</code> to import it. Now we can see the error that says that it's private:</p>
<p>It's easy to understand that function <code>print_one_thing</code> is private. It also shows us with <code>src\main.rs:4:5</code> where to find the function. This is helpful because you can write <code>mod</code>s not just in one file, but over a lot of files as well.</p>
<p>Now we just write <code>pub fn</code> instead of <code>fn</code> and everything works.</p>
<p>How about <code>pub</code> for a struct, enum, trait, or module? <code>pub</code> works like this for them:</p>
<ul>
<li><code>pub</code> for a struct: it makes the struct public, but the items are not public. To make an item public, you have to write <code>pub</code> for each one too.</li>
<li><code>pub</code> for an enum or trait: everything becomes public. This makes sense because traits are about giving the same behaviour to something. And enums are about choosing between items, and you need to see them all to choose them.</li>
<li><code>pub</code> for a module: a top level module will be <code>pub</code> because if it isn't pub then nobody can touch anything in it at all. But modules inside modules need <code>pub</code> to be public.</li>
</ul>
<p>So let's put a struct named <code>Billy</code> inside <code>print_things</code>. This struct will be almost all public, but not quite. The struct is public so it will say <code>pub struct Billy</code>. Inside it will have a <code>name</code> and <code>times_to_print</code>. <code>name</code> will not be public, because we only want the user to create structs named <code>"Billy".to_string()</code>. But the user can select the number of times to print, so that will be public. It looks like this:</p>
pub fn new(times_to_print: u32) -> Self { // That means the user needs to use new to create a Billy. The user can only change the number of times_to_print
Self {
name: "Billy".to_string(), // We choose the name - the user can't
<p>By the way, the <code>*</code> to import everything is called the "glob operator". Glob means "global", so it means everything.</p>
<p>Inside a <code>mod</code> you can create other mods. A child mod (a mod inside of a mod) can always use anything inside a parent mod. You can see this in the next example where we have a <code>mod city</code> inside a <code>mod province</code> inside a <code>mod country</code>.</p>
<p>You can think of the structure like this: even if you are in a country, you might not be in a province. And even if you are in a province, you might not be in a city. But if you are in a city, you are in its province and you are in its country.</p>
<pre><preclass="playground"><codeclass="language-rust">mod country { // The main mod doesn't need pub
fn print_country(country: &str) { // Note: this function isn't public
println!("We are in the country of {}", country);
<p>The interesting part is that <code>print_city</code> can access <code>print_province</code> and <code>print_country</code>. That's because <code>mod city</code> is inside the other mods. It doesn't need <code>pub</code> in front of <code>print_province</code> to use it. And that makes sense: a city doesn't need to do anything to be inside a province and inside a country.</p>
<p>You probably noticed that <code>crate::country::province::print_province(province);</code> is very long. When we are inside a module we can use <code>super</code> to bring in items from above. Actually the word super itself means "above", like in "superior". In our example we only used the function once, but if you use it more then it is a good idea to import. It can also be a good idea if it makes your code easier to read, even if you only use the function once. The code is almost the same now, but a bit easier to read:</p>
<pre><preclass="playground"><codeclass="language-rust">mod country {
fn print_country(country: &str) {
println!("We are in the country of {}", country);
}
pub mod province {
fn print_province(province: &str) {
println!("in the province of {}", province);
