-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathch02-00-guessing-game-tutorial.html
More file actions
1247 lines (1181 loc) · 84.1 KB
/
ch02-00-guessing-game-tutorial.html
File metadata and controls
1247 lines (1181 loc) · 84.1 KB
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
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Programming a Guessing Game - The Rust Programming Language</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- 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 -->
<link rel="stylesheet" href="ferris.css">
<link rel="stylesheet" href="theme/2018-edition.css">
</head>
<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" : "light";
</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('light')
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">
<ol class="chapter"><li class="chapter-item expanded affix "><a href="title-page.html">The Rust Programming Language</a></li><li class="chapter-item expanded affix "><a href="foreword.html">Foreword</a></li><li class="chapter-item expanded affix "><a href="ch00-00-introduction.html">Introduction</a></li><li class="chapter-item expanded "><a href="ch01-00-getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch01-01-installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li class="chapter-item expanded "><a href="ch01-02-hello-world.html"><strong aria-hidden="true">1.2.</strong> Hello, World!</a></li><li class="chapter-item expanded "><a href="ch01-03-hello-cargo.html"><strong aria-hidden="true">1.3.</strong> Hello, Cargo!</a></li></ol></li><li class="chapter-item expanded "><a href="ch02-00-guessing-game-tutorial.html" class="active"><strong aria-hidden="true">2.</strong> Programming a Guessing Game</a></li><li class="chapter-item expanded "><a href="ch03-00-common-programming-concepts.html"><strong aria-hidden="true">3.</strong> Common Programming Concepts</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch03-01-variables-and-mutability.html"><strong aria-hidden="true">3.1.</strong> Variables and Mutability</a></li><li class="chapter-item expanded "><a href="ch03-02-data-types.html"><strong aria-hidden="true">3.2.</strong> Data Types</a></li><li class="chapter-item expanded "><a href="ch03-03-how-functions-work.html"><strong aria-hidden="true">3.3.</strong> Functions</a></li><li class="chapter-item expanded "><a href="ch03-04-comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li class="chapter-item expanded "><a href="ch03-05-control-flow.html"><strong aria-hidden="true">3.5.</strong> Control Flow</a></li></ol></li><li class="chapter-item expanded "><a href="ch04-00-understanding-ownership.html"><strong aria-hidden="true">4.</strong> Understanding Ownership</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch04-01-what-is-ownership.html"><strong aria-hidden="true">4.1.</strong> What is Ownership?</a></li><li class="chapter-item expanded "><a href="ch04-02-references-and-borrowing.html"><strong aria-hidden="true">4.2.</strong> References and Borrowing</a></li><li class="chapter-item expanded "><a href="ch04-03-slices.html"><strong aria-hidden="true">4.3.</strong> The Slice Type</a></li></ol></li><li class="chapter-item expanded "><a href="ch05-00-structs.html"><strong aria-hidden="true">5.</strong> Using Structs to Structure Related Data</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch05-01-defining-structs.html"><strong aria-hidden="true">5.1.</strong> Defining and Instantiating Structs</a></li><li class="chapter-item expanded "><a href="ch05-02-example-structs.html"><strong aria-hidden="true">5.2.</strong> An Example Program Using Structs</a></li><li class="chapter-item expanded "><a href="ch05-03-method-syntax.html"><strong aria-hidden="true">5.3.</strong> Method Syntax</a></li></ol></li><li class="chapter-item expanded "><a href="ch06-00-enums.html"><strong aria-hidden="true">6.</strong> Enums and Pattern Matching</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch06-01-defining-an-enum.html"><strong aria-hidden="true">6.1.</strong> Defining an Enum</a></li><li class="chapter-item expanded "><a href="ch06-02-match.html"><strong aria-hidden="true">6.2.</strong> The match Control Flow Operator</a></li><li class="chapter-item expanded "><a href="ch06-03-if-let.html"><strong aria-hidden="true">6.3.</strong> Concise Control Flow with if let</a></li></ol></li><li class="chapter-item expanded "><a href="ch07-00-managing-growing-projects-with-packages-crates-and-modules.html"><strong aria-hidden="true">7.</strong> Managing Growing Projects with Packages, Crates, and Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch07-01-packages-and-crates.html"><strong aria-hidden="true">7.1.</strong> Packages and Crates</a></li><li class="chapter-item expanded "><a href="ch07-02-defining-modules-to-control-scope-and-privacy.html"><strong aria-hidden="true">7.2.</strong> Defining Modules to Control Scope and Privacy</a></li><li class="chapter-item expanded "><a href="ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html"><strong aria-hidden="true">7.3.</strong> Paths for Referring to an Item in the Module Tree</a></li><li class="chapter-item expanded "><a href="ch07-04-bringing-paths-into-scope-with-the-use-keyword.html"><strong aria-hidden="true">7.4.</strong> Bringing Paths Into Scope with the use Keyword</a></li><li class="chapter-item expanded "><a href="ch07-05-separating-modules-into-different-files.html"><strong aria-hidden="true">7.5.</strong> Separating Modules into Different Files</a></li></ol></li><li class="chapter-item expanded "><a href="ch08-00-common-collections.html"><strong aria-hidden="true">8.</strong> Common Collections</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch08-01-vectors.html"><strong aria-hidden="true">8.1.</strong> Storing Lists of Values with Vectors</a></li><li class="chapter-item expanded "><a href="ch08-02-strings.html"><strong aria-hidden="true">8.2.</strong> Storing UTF-8 Encoded Text with Strings</a></li><li class="chapter-item expanded "><a href="ch08-03-hash-maps.html"><strong aria-hidden="true">8.3.</strong> Storing Keys with Associated Values in Hash Maps</a></li></ol></li><li class="chapter-item expanded "><a href="ch09-00-error-handling.html"><strong aria-hidden="true">9.</strong> Error Handling</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch09-01-unrecoverable-errors-with-panic.html"><strong aria-hidden="true">9.1.</strong> Unrecoverable Errors with panic!</a></li><li class="chapter-item expanded "><a href="ch09-02-recoverable-errors-with-result.html"><strong aria-hidden="true">9.2.</strong> Recoverable Errors with Result</a></li><li class="chapter-item expanded "><a href="ch09-03-to-panic-or-not-to-panic.html"><strong aria-hidden="true">9.3.</strong> To panic! or Not To panic!</a></li></ol></li><li class="chapter-item expanded "><a href="ch10-00-generics.html"><strong aria-hidden="true">10.</strong> Generic Types, Traits, and Lifetimes</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch10-01-syntax.html"><strong aria-hidden="true">10.1.</strong> Generic Data Types</a></li><li class="chapter-item expanded "><a href="ch10-02-traits.html"><strong aria-hidden="true">10.2.</strong> Traits: Defining Shared Behavior</a></li><li class="chapter-item expanded "><a href="ch10-03-lifetime-syntax.html"><strong aria-hidden="true">10.3.</strong> Validating References with Lifetimes</a></li></ol></li><li class="chapter-item expanded "><a href="ch11-00-testing.html"><strong aria-hidden="true">11.</strong> Writing Automated Tests</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch11-01-writing-tests.html"><strong aria-hidden="true">11.1.</strong> How to Write Tests</a></li><li class="chapter-item expanded "><a href="ch11-02-running-tests.html"><strong aria-hidden="true">11.2.</strong> Controlling How Tests Are Run</a></li><li class="chapter-item expanded "><a href="ch11-03-test-organization.html"><strong aria-hidden="true">11.3.</strong> Test Organization</a></li></ol></li><li class="chapter-item expanded "><a href="ch12-00-an-io-project.html"><strong aria-hidden="true">12.</strong> An I/O Project: Building a Command Line Program</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch12-01-accepting-command-line-arguments.html"><strong aria-hidden="true">12.1.</strong> Accepting Command Line Arguments</a></li><li class="chapter-item expanded "><a href="ch12-02-reading-a-file.html"><strong aria-hidden="true">12.2.</strong> Reading a File</a></li><li class="chapter-item expanded "><a href="ch12-03-improving-error-handling-and-modularity.html"><strong aria-hidden="true">12.3.</strong> Refactoring to Improve Modularity and Error Handling</a></li><li class="chapter-item expanded "><a href="ch12-04-testing-the-librarys-functionality.html"><strong aria-hidden="true">12.4.</strong> Developing the Library’s Functionality with Test Driven Development</a></li><li class="chapter-item expanded "><a href="ch12-05-working-with-environment-variables.html"><strong aria-hidden="true">12.5.</strong> Working with Environment Variables</a></li><li class="chapter-item expanded "><a href="ch12-06-writing-to-stderr-instead-of-stdout.html"><strong aria-hidden="true">12.6.</strong> Writing Error Messages to Standard Error Instead of Standard Output</a></li></ol></li><li class="chapter-item expanded "><a href="ch13-00-functional-features.html"><strong aria-hidden="true">13.</strong> Functional Language Features: Iterators and Closures</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch13-01-closures.html"><strong aria-hidden="true">13.1.</strong> Closures: Anonymous Functions that Can Capture Their Environment</a></li><li class="chapter-item expanded "><a href="ch13-02-iterators.html"><strong aria-hidden="true">13.2.</strong> Processing a Series of Items with Iterators</a></li><li class="chapter-item expanded "><a href="ch13-03-improving-our-io-project.html"><strong aria-hidden="true">13.3.</strong> Improving Our I/O Project</a></li><li class="chapter-item expanded "><a href="ch13-04-performance.html"><strong aria-hidden="true">13.4.</strong> Comparing Performance: Loops vs. Iterators</a></li></ol></li><li class="chapter-item expanded "><a href="ch14-00-more-about-cargo.html"><strong aria-hidden="true">14.</strong> More about Cargo and Crates.io</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch14-01-release-profiles.html"><strong aria-hidden="true">14.1.</strong> Customizing Builds with Release Profiles</a></li><li class="chapter-item expanded "><a href="ch14-02-publishing-to-crates-io.html"><strong aria-hidden="true">14.2.</strong> Publishing a Crate to Crates.io</a></li><li class="chapter-item expanded "><a href="ch14-03-cargo-workspaces.html"><strong aria-hidden="true">14.3.</strong> Cargo Workspaces</a></li><li class="chapter-item expanded "><a href="ch14-04-installing-binaries.html"><strong aria-hidden="true">14.4.</strong> Installing Binaries from Crates.io with cargo install</a></li><li class="chapter-item expanded "><a href="ch14-05-extending-cargo.html"><strong aria-hidden="true">14.5.</strong> Extending Cargo with Custom Commands</a></li></ol></li><li class="chapter-item expanded "><a href="ch15-00-smart-pointers.html"><strong aria-hidden="true">15.</strong> Smart Pointers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch15-01-box.html"><strong aria-hidden="true">15.1.</strong> Using Box<T> to Point to Data on the Heap</a></li><li class="chapter-item expanded "><a href="ch15-02-deref.html"><strong aria-hidden="true">15.2.</strong> Treating Smart Pointers Like Regular References with the Deref Trait</a></li><li class="chapter-item expanded "><a href="ch15-03-drop.html"><strong aria-hidden="true">15.3.</strong> Running Code on Cleanup with the Drop Trait</a></li><li class="chapter-item expanded "><a href="ch15-04-rc.html"><strong aria-hidden="true">15.4.</strong> Rc<T>, the Reference Counted Smart Pointer</a></li><li class="chapter-item expanded "><a href="ch15-05-interior-mutability.html"><strong aria-hidden="true">15.5.</strong> RefCell<T> and the Interior Mutability Pattern</a></li><li class="chapter-item expanded "><a href="ch15-06-reference-cycles.html"><strong aria-hidden="true">15.6.</strong> Reference Cycles Can Leak Memory</a></li></ol></li><li class="chapter-item expanded "><a href="ch16-00-concurrency.html"><strong aria-hidden="true">16.</strong> Fearless Concurrency</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch16-01-threads.html"><strong aria-hidden="true">16.1.</strong> Using Threads to Run Code Simultaneously</a></li><li class="chapter-item expanded "><a href="ch16-02-message-passing.html"><strong aria-hidden="true">16.2.</strong> Using Message Passing to Transfer Data Between Threads</a></li><li class="chapter-item expanded "><a href="ch16-03-shared-state.html"><strong aria-hidden="true">16.3.</strong> Shared-State Concurrency</a></li><li class="chapter-item expanded "><a href="ch16-04-extensible-concurrency-sync-and-send.html"><strong aria-hidden="true">16.4.</strong> Extensible Concurrency with the Sync and Send Traits</a></li></ol></li><li class="chapter-item expanded "><a href="ch17-00-oop.html"><strong aria-hidden="true">17.</strong> Object Oriented Programming Features of Rust</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch17-01-what-is-oo.html"><strong aria-hidden="true">17.1.</strong> Characteristics of Object-Oriented Languages</a></li><li class="chapter-item expanded "><a href="ch17-02-trait-objects.html"><strong aria-hidden="true">17.2.</strong> Using Trait Objects That Allow for Values of Different Types</a></li><li class="chapter-item expanded "><a href="ch17-03-oo-design-patterns.html"><strong aria-hidden="true">17.3.</strong> Implementing an Object-Oriented Design Pattern</a></li></ol></li><li class="chapter-item expanded "><a href="ch18-00-patterns.html"><strong aria-hidden="true">18.</strong> Patterns and Matching</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch18-01-all-the-places-for-patterns.html"><strong aria-hidden="true">18.1.</strong> All the Places Patterns Can Be Used</a></li><li class="chapter-item expanded "><a href="ch18-02-refutability.html"><strong aria-hidden="true">18.2.</strong> Refutability: Whether a Pattern Might Fail to Match</a></li><li class="chapter-item expanded "><a href="ch18-03-pattern-syntax.html"><strong aria-hidden="true">18.3.</strong> Pattern Syntax</a></li></ol></li><li class="chapter-item expanded "><a href="ch19-00-advanced-features.html"><strong aria-hidden="true">19.</strong> Advanced Features</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch19-01-unsafe-rust.html"><strong aria-hidden="true">19.1.</strong> Unsafe Rust</a></li><li class="chapter-item expanded "><a href="ch19-03-advanced-traits.html"><strong aria-hidden="true">19.2.</strong> Advanced Traits</a></li><li class="chapter-item expanded "><a href="ch19-04-advanced-types.html"><strong aria-hidden="true">19.3.</strong> Advanced Types</a></li><li class="chapter-item expanded "><a href="ch19-05-advanced-functions-and-closures.html"><strong aria-hidden="true">19.4.</strong> Advanced Functions and Closures</a></li><li class="chapter-item expanded "><a href="ch19-06-macros.html"><strong aria-hidden="true">19.5.</strong> Macros</a></li></ol></li><li class="chapter-item expanded "><a href="ch20-00-final-project-a-web-server.html"><strong aria-hidden="true">20.</strong> Final Project: Building a Multithreaded Web Server</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ch20-01-single-threaded.html"><strong aria-hidden="true">20.1.</strong> Building a Single-Threaded Web Server</a></li><li class="chapter-item expanded "><a href="ch20-02-multithreaded.html"><strong aria-hidden="true">20.2.</strong> Turning Our Single-Threaded Server into a Multithreaded Server</a></li><li class="chapter-item expanded "><a href="ch20-03-graceful-shutdown-and-cleanup.html"><strong aria-hidden="true">20.3.</strong> Graceful Shutdown and Cleanup</a></li></ol></li><li class="chapter-item expanded "><a href="appendix-00.html"><strong aria-hidden="true">21.</strong> Appendix</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="appendix-01-keywords.html"><strong aria-hidden="true">21.1.</strong> A - Keywords</a></li><li class="chapter-item expanded "><a href="appendix-02-operators.html"><strong aria-hidden="true">21.2.</strong> B - Operators and Symbols</a></li><li class="chapter-item expanded "><a href="appendix-03-derivable-traits.html"><strong aria-hidden="true">21.3.</strong> C - Derivable Traits</a></li><li class="chapter-item expanded "><a href="appendix-04-useful-development-tools.html"><strong aria-hidden="true">21.4.</strong> D - Useful Development Tools</a></li><li class="chapter-item expanded "><a href="appendix-05-editions.html"><strong aria-hidden="true">21.5.</strong> E - Editions</a></li><li class="chapter-item expanded "><a href="appendix-06-translation.html"><strong aria-hidden="true">21.6.</strong> F - Translations of the Book</a></li><li class="chapter-item expanded "><a href="appendix-07-nightly-rust.html"><strong aria-hidden="true">21.7.</strong> G - How Rust is Made and “Nightly Rust”</a></li></ol></li></ol>
</div>
<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 (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</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>
<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">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Rust Programming Language</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/rust-lang-vn/book-src" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</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>
<h1 id="programming-a-guessing-game"><a class="header" href="#programming-a-guessing-game">Programming a Guessing Game</a></h1>
<p>Let’s jump into Rust by working through a hands-on project together! This
chapter introduces you to a few common Rust concepts by showing you how to use
them in a real program. You’ll learn about <code>let</code>, <code>match</code>, methods, associated
functions, using external crates, and more! The following chapters will explore
these ideas in more detail. In this chapter, you’ll practice the fundamentals.</p>
<p>We’ll implement a classic beginner programming problem: a guessing game. Here’s
how it works: the program will generate a random integer between 1 and 100. It
will then prompt the player to enter a guess. After a guess is entered, the
program will indicate whether the guess is too low or too high. If the guess is
correct, the game will print a congratulatory message and exit.</p>
<h2 id="setting-up-a-new-project"><a class="header" href="#setting-up-a-new-project">Setting Up a New Project</a></h2>
<p>To set up a new project, go to the <em>projects</em> directory that you created in
Chapter 1 and make a new project using Cargo, like so:</p>
<pre><code class="language-console">$ cargo new guessing_game
$ cd guessing_game
</code></pre>
<p>The first command, <code>cargo new</code>, takes the name of the project (<code>guessing_game</code>)
as the first argument. The second command changes to the new project’s
directory.</p>
<p>Look at the generated <em>Cargo.toml</em> file:</p>
<p><span class="filename">Filename: Cargo.toml</span></p>
<pre><code class="language-toml">[package]
name = "guessing_game"
version = "0.1.0"
edition = "2018"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]
</code></pre>
<p>As you saw in Chapter 1, <code>cargo new</code> generates a “Hello, world!” program for
you. Check out the <em>src/main.rs</em> file:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playground"><code class="language-rust">fn main() {
println!("Hello, world!");
}
</code></pre></pre>
<p>Now let’s compile this “Hello, world!” program and run it in the same step
using the <code>cargo run</code> command:</p>
<pre><code class="language-console">$ cargo run
Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
Finished dev [unoptimized + debuginfo] target(s) in 1.50s
Running `target/debug/guessing_game`
Hello, world!
</code></pre>
<p>The <code>run</code> command comes in handy when you need to rapidly iterate on a project,
as we’ll do in this game, quickly testing each iteration before moving on to
the next one.</p>
<p>Reopen the <em>src/main.rs</em> file. You’ll be writing all the code in this file.</p>
<h2 id="processing-a-guess"><a class="header" href="#processing-a-guess">Processing a Guess</a></h2>
<p>The first part of the guessing game program will ask for user input, process
that input, and check that the input is in the expected form. To start, we’ll
allow the player to input a guess. Enter the code in Listing 2-1 into
<em>src/main.rs</em>.</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore">use std::io;
fn main() {
println!("Guess the number!");
println!("Please input your guess.");
let mut guess = String::new();
io::stdin()
.read_line(&mut guess)
.expect("Failed to read line");
println!("You guessed: {}", guess);
}
</code></pre>
<p><span class="caption">Listing 2-1: Code that gets a guess from the user and
prints it</span></p>
<p>This code contains a lot of information, so let’s go over it line by line. To
obtain user input and then print the result as output, we need to bring the
<code>io</code> (input/output) library into scope. The <code>io</code> library comes from the
standard library (which is known as <code>std</code>):</p>
<pre><code class="language-rust ignore">use std::io;
<span class="boring">
</span><span class="boring">fn main() {
</span><span class="boring"> println!("Guess the number!");
</span><span class="boring">
</span><span class="boring"> println!("Please input your guess.");
</span><span class="boring">
</span><span class="boring"> let mut guess = String::new();
</span><span class="boring">
</span><span class="boring"> io::stdin()
</span><span class="boring"> .read_line(&mut guess)
</span><span class="boring"> .expect("Failed to read line");
</span><span class="boring">
</span><span class="boring"> println!("You guessed: {}", guess);
</span><span class="boring">}
</span></code></pre>
<p>By default, Rust brings only a few types into the scope of every program in
<a href="../std/prelude/index.html">the <em>prelude</em></a><!-- ignore -->. If a type you want to use isn’t in the
prelude, you have to bring that type into scope explicitly with a <code>use</code>
statement. Using the <code>std::io</code> library provides you with a number of useful
features, including the ability to accept user input.</p>
<p>As you saw in Chapter 1, the <code>main</code> function is the entry point into the
program:</p>
<pre><code class="language-rust ignore"><span class="boring">use std::io;
</span><span class="boring">
</span>fn main() {
<span class="boring"> println!("Guess the number!");
</span><span class="boring">
</span><span class="boring"> println!("Please input your guess.");
</span><span class="boring">
</span><span class="boring"> let mut guess = String::new();
</span><span class="boring">
</span><span class="boring"> io::stdin()
</span><span class="boring"> .read_line(&mut guess)
</span><span class="boring"> .expect("Failed to read line");
</span><span class="boring">
</span><span class="boring"> println!("You guessed: {}", guess);
</span><span class="boring">}
</span></code></pre>
<p>The <code>fn</code> syntax declares a new function, the parentheses, <code>()</code>, indicate there
are no parameters, and the curly bracket, <code>{</code>, starts the body of the function.</p>
<p>As you also learned in Chapter 1, <code>println!</code> is a macro that prints a string to
the screen:</p>
<pre><code class="language-rust ignore"><span class="boring">use std::io;
</span><span class="boring">
</span><span class="boring">fn main() {
</span> println!("Guess the number!");
println!("Please input your guess.");
<span class="boring">
</span><span class="boring"> let mut guess = String::new();
</span><span class="boring">
</span><span class="boring"> io::stdin()
</span><span class="boring"> .read_line(&mut guess)
</span><span class="boring"> .expect("Failed to read line");
</span><span class="boring">
</span><span class="boring"> println!("You guessed: {}", guess);
</span><span class="boring">}
</span></code></pre>
<p>This code is printing a prompt stating what the game is and requesting input
from the user.</p>
<h3 id="storing-values-with-variables"><a class="header" href="#storing-values-with-variables">Storing Values with Variables</a></h3>
<p>Next, we’ll create a place to store the user input, like this:</p>
<pre><code class="language-rust ignore"><span class="boring">use std::io;
</span><span class="boring">
</span><span class="boring">fn main() {
</span><span class="boring"> println!("Guess the number!");
</span><span class="boring">
</span><span class="boring"> println!("Please input your guess.");
</span><span class="boring">
</span> let mut guess = String::new();
<span class="boring">
</span><span class="boring"> io::stdin()
</span><span class="boring"> .read_line(&mut guess)
</span><span class="boring"> .expect("Failed to read line");
</span><span class="boring">
</span><span class="boring"> println!("You guessed: {}", guess);
</span><span class="boring">}
</span></code></pre>
<p>Now the program is getting interesting! There’s a lot going on in this little
line. Notice that this is a <code>let</code> statement, which is used to create a
<em>variable</em>. Here’s another example:</p>
<pre><code class="language-rust ignore">let apples = 5;
</code></pre>
<p>This line creates a new variable named <code>apples</code> and binds it to the value 5. In
Rust, variables are immutable by default. We’ll be discussing this concept in
detail in the <a href="ch03-01-variables-and-mutability.html#variables-and-mutability">“Variables and Mutability”</a><!-- ignore
--> section in Chapter 3. The following example shows how to use <code>mut</code> before
the variable name to make a variable mutable:</p>
<pre><code class="language-rust ignore">let apples = 5; // immutable
let mut bananas = 5; // mutable
</code></pre>
<blockquote>
<p>Note: The <code>//</code> syntax starts a comment that continues until the end of the
line. Rust ignores everything in comments, which are discussed in more detail
in Chapter 3.</p>
</blockquote>
<p>Let’s return to the guessing game program. You now know that <code>let mut guess</code>
will introduce a mutable variable named <code>guess</code>. On the other side of the equal
sign (<code>=</code>) is the value that <code>guess</code> is bound to, which is the result of
calling <code>String::new</code>, a function that returns a new instance of a <code>String</code>.
<a href="../std/string/struct.String.html"><code>String</code></a><!-- ignore --> is a string type provided by the standard
library that is a growable, UTF-8 encoded bit of text.</p>
<p>The <code>::</code> syntax in the <code>::new</code> line indicates that <code>new</code> is an <em>associated
function</em> of the <code>String</code> type. An associated function is implemented on a
type, in this case <code>String</code>.</p>
<p>This <code>new</code> function creates a new, empty string. You’ll find a <code>new</code> function
on many types, because it’s a common name for a function that makes a new value
of some kind.</p>
<p>To summarize, the <code>let mut guess = String::new();</code> line has created a mutable
variable that is currently bound to a new, empty instance of a <code>String</code>. Whew!</p>
<p>Recall that we included the input/output functionality from the standard
library with <code>use std::io;</code> on the first line of the program. Now we’ll call
the <code>stdin</code> function from the <code>io</code> module:</p>
<pre><code class="language-rust ignore"><span class="boring">use std::io;
</span><span class="boring">
</span><span class="boring">fn main() {
</span><span class="boring"> println!("Guess the number!");
</span><span class="boring">
</span><span class="boring"> println!("Please input your guess.");
</span><span class="boring">
</span><span class="boring"> let mut guess = String::new();
</span><span class="boring">
</span> io::stdin()
.read_line(&mut guess)
<span class="boring"> .expect("Failed to read line");
</span><span class="boring">
</span><span class="boring"> println!("You guessed: {}", guess);
</span><span class="boring">}
</span></code></pre>
<p>If we hadn’t put the <code>use std::io</code> line at the beginning of the program, we
could have written this function call as <code>std::io::stdin</code>. The <code>stdin</code> function
returns an instance of <a href="../std/io/struct.Stdin.html"><code>std::io::Stdin</code></a><!-- ignore -->, which is a
type that represents a handle to the standard input for your terminal.</p>
<p>The next part of the code, <code>.read_line(&mut guess)</code>, calls the
<a href="../std/io/struct.Stdin.html#method.read_line"><code>read_line</code></a><!-- ignore --> method on the standard input handle to
get input from the user. We’re also passing one argument to <code>read_line</code>: <code>&mut guess</code>.</p>
<p>The job of <code>read_line</code> is to take whatever the user types into standard input
and append that into a string (without overwriting its contents), so it takes
that string as an argument. The string argument needs to be mutable so the
method can change the string’s content by adding the user input.</p>
<p>The <code>&</code> indicates that this argument is a <em>reference</em>, which gives you a way to
let multiple parts of your code access one piece of data without needing to
copy that data into memory multiple times. References are a complex feature,
and one of Rust’s major advantages is how safe and easy it is to use
references. You don’t need to know a lot of those details to finish this
program. For now, all you need to know is that like variables, references are
immutable by default. Hence, you need to write <code>&mut guess</code> rather than
<code>&guess</code> to make it mutable. (Chapter 4 will explain references more
thoroughly.)</p>
<h3 id="handling-potential-failure-with-the-result-type"><a class="header" href="#handling-potential-failure-with-the-result-type">Handling Potential Failure with the <code>Result</code> Type</a></h3>
<p>We’re still working on this line of code. Although we’re now discussing a third
line of text, it’s still part of a single logical line of code. The next part
is this method:</p>
<pre><code class="language-rust ignore"><span class="boring">use std::io;
</span><span class="boring">
</span><span class="boring">fn main() {
</span><span class="boring"> println!("Guess the number!");
</span><span class="boring">
</span><span class="boring"> println!("Please input your guess.");
</span><span class="boring">
</span><span class="boring"> let mut guess = String::new();
</span><span class="boring">
</span><span class="boring"> io::stdin()
</span><span class="boring"> .read_line(&mut guess)
</span> .expect("Failed to read line");
<span class="boring">
</span><span class="boring"> println!("You guessed: {}", guess);
</span><span class="boring">}
</span></code></pre>
<p>When you call a method with the <code>.method_name()</code> syntax, it’s often wise to
introduce a newline and other whitespace to help break up long lines. We could
have written this code as:</p>
<pre><code class="language-rust ignore">io::stdin().read_line(&mut guess).expect("Failed to read line");
</code></pre>
<p>However, one long line is difficult to read, so it’s best to divide it. Now
let’s discuss what this line does.</p>
<p>As mentioned earlier, <code>read_line</code> puts what the user types into the string
we’re passing it, but it also returns a value—in this case, an
<a href="../std/io/type.Result.html"><code>io::Result</code></a><!-- ignore -->. Rust has a number of types named
<code>Result</code> in its standard library: a generic <a href="../std/result/enum.Result.html"><code>Result</code></a><!-- ignore -->
as well as specific versions for submodules, such as <code>io::Result</code>.</p>
<p>The <code>Result</code> types are <a href="ch06-00-enums.html"><em>enumerations</em></a><!-- ignore -->, often referred
to as <em>enums</em>. An enumeration is a type that can have a fixed set of values,
and those values are called the enum’s <em>variants</em>. Chapter 6 will cover enums
in more detail.</p>
<p>For <code>Result</code>, the variants are <code>Ok</code> or <code>Err</code>. The <code>Ok</code> variant indicates the
operation was successful, and inside <code>Ok</code> is the successfully generated value.
The <code>Err</code> variant means the operation failed, and <code>Err</code> contains information
about how or why the operation failed.</p>
<p>The purpose of these <code>Result</code> types is to encode error-handling information.
Values of the <code>Result</code> type, like values of any type, have methods defined on
them. An instance of <code>io::Result</code> has an <a href="../std/result/enum.Result.html#method.expect"><code>expect</code> method</a><!-- ignore
--> that you can call. If this instance of <code>io::Result</code> is an <code>Err</code> value,
<code>expect</code> will cause the program to crash and display the message that you
passed as an argument to <code>expect</code>. If the <code>read_line</code> method returns an <code>Err</code>,
it would likely be the result of an error coming from the underlying operating
system. If this instance of <code>io::Result</code> is an <code>Ok</code> value, <code>expect</code> will take
the return value that <code>Ok</code> is holding and return just that value to you so you
can use it. In this case, that value is the number of bytes in what the user
entered into standard input.</p>
<p>If you don’t call <code>expect</code>, the program will compile, but you’ll get a warning:</p>
<pre><code class="language-console">$ cargo build
Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
warning: unused `Result` that must be used
--> src/main.rs:10:5
|
10 | io::stdin().read_line(&mut guess);
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= note: `#[warn(unused_must_use)]` on by default
= note: this `Result` may be an `Err` variant, which should be handled
warning: 1 warning emitted
Finished dev [unoptimized + debuginfo] target(s) in 0.59s
</code></pre>
<p>Rust warns that you haven’t used the <code>Result</code> value returned from <code>read_line</code>,
indicating that the program hasn’t handled a possible error.</p>
<p>The right way to suppress the warning is to actually write error handling, but
because you just want to crash this program when a problem occurs, you can use
<code>expect</code>. You’ll learn about recovering from errors in Chapter 9.</p>
<h3 id="printing-values-with-println-placeholders"><a class="header" href="#printing-values-with-println-placeholders">Printing Values with <code>println!</code> Placeholders</a></h3>
<p>Aside from the closing curly bracket, there’s only one more line to discuss in
the code added so far, which is the following:</p>
<pre><code class="language-rust ignore"><span class="boring">use std::io;
</span><span class="boring">
</span><span class="boring">fn main() {
</span><span class="boring"> println!("Guess the number!");
</span><span class="boring">
</span><span class="boring"> println!("Please input your guess.");
</span><span class="boring">
</span><span class="boring"> let mut guess = String::new();
</span><span class="boring">
</span><span class="boring"> io::stdin()
</span><span class="boring"> .read_line(&mut guess)
</span><span class="boring"> .expect("Failed to read line");
</span><span class="boring">
</span> println!("You guessed: {}", guess);
<span class="boring">}
</span></code></pre>
<p>This line prints the string we saved the user’s input in. The set of curly
brackets, <code>{}</code>, is a placeholder: think of <code>{}</code> as little crab pincers that
hold a value in place. You can print more than one value using curly brackets:
the first set of curly brackets holds the first value listed after the format
string, the second set holds the second value, and so on. Printing multiple
values in one call to <code>println!</code> would look like this:</p>
<pre><pre class="playground"><code class="language-rust">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>let x = 5;
let y = 10;
println!("x = {} and y = {}", x, y);
<span class="boring">}
</span></code></pre></pre>
<p>This code would print <code>x = 5 and y = 10</code>.</p>
<h3 id="testing-the-first-part"><a class="header" href="#testing-the-first-part">Testing the First Part</a></h3>
<p>Let’s test the first part of the guessing game. Run it using <code>cargo run</code>:</p>
<!-- manual-regeneration
cd listings/ch02-guessing-game-tutorial/listing-02-01/
cargo clean
cargo run
input 6 -->
<pre><code class="language-console">$ cargo run
Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
Finished dev [unoptimized + debuginfo] target(s) in 6.44s
Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
6
You guessed: 6
</code></pre>
<p>At this point, the first part of the game is done: we’re getting input from the
keyboard and then printing it.</p>
<h2 id="generating-a-secret-number"><a class="header" href="#generating-a-secret-number">Generating a Secret Number</a></h2>
<p>Next, we need to generate a secret number that the user will try to guess. The
secret number should be different every time so the game is fun to play more
than once. Let’s use a random number between 1 and 100 so the game isn’t too
difficult. Rust doesn’t yet include random number functionality in its standard
library. However, the Rust team does provide a <a href="https://crates.io/crates/rand"><code>rand</code> crate</a>.</p>
<h3 id="using-a-crate-to-get-more-functionality"><a class="header" href="#using-a-crate-to-get-more-functionality">Using a Crate to Get More Functionality</a></h3>
<p>Remember that a crate is a collection of Rust source code files. The project
we’ve been building is a <em>binary crate</em>, which is an executable. The <code>rand</code>
crate is a <em>library crate</em>, which contains code intended to be used in other
programs.</p>
<p>Cargo’s coordination of external crates is where Cargo really shines. Before we
can write code that uses <code>rand</code>, we need to modify the <em>Cargo.toml</em> file to
include the <code>rand</code> crate as a dependency. Open that file now and add the
following line to the bottom beneath the <code>[dependencies]</code> section header that
Cargo created for you. Be sure to specify <code>rand</code> exactly as we have here, or
the code examples in this tutorial may not work.</p>
<!-- When updating the version of `rand` used, also update the version of
`rand` used in these files so they all match:
* ch07-04-bringing-paths-into-scope-with-the-use-keyword.md
* ch14-03-cargo-workspaces.md
-->
<p><span class="filename">Filename: Cargo.toml</span></p>
<pre><code class="language-toml">rand = "0.8.3"
</code></pre>
<p>In the <em>Cargo.toml</em> file, everything that follows a header is part of a section
that continues until another section starts. The <code>[dependencies]</code> section is
where you tell Cargo which external crates your project depends on and which
versions of those crates you require. In this case, we’ll specify the <code>rand</code>
crate with the semantic version specifier <code>0.8.3</code>. Cargo understands <a href="http://semver.org">Semantic
Versioning</a><!-- ignore --> (sometimes called <em>SemVer</em>), which is a
standard for writing version numbers. The number <code>0.8.3</code> is actually shorthand
for <code>^0.8.3</code>, which means any version that is at least <code>0.8.3</code> but below
<code>0.9.0</code>. Cargo considers these versions to have public APIs compatible with
version <code>0.8.3</code>, and this specification ensures you'll get the latest patch
release that will still compile with the code in this chapter. Any version
<code>0.9.0</code> or greater is not guaranteed to have the same API as what the following
examples use.</p>
<p>Now, without changing any of the code, let’s build the project, as shown in
Listing 2-2.</p>
<!-- manual-regeneration
cd listings/ch02-guessing-game-tutorial/listing-02-02/
cargo clean
cargo build -->
<pre><code class="language-console">$ cargo build
Updating crates.io index
Downloaded rand v0.8.3
Downloaded libc v0.2.86
Downloaded getrandom v0.2.2
Downloaded cfg-if v1.0.0
Downloaded ppv-lite86 v0.2.10
Downloaded rand_chacha v0.3.0
Downloaded rand_core v0.6.2
Compiling rand_core v0.6.2
Compiling libc v0.2.86
Compiling getrandom v0.2.2
Compiling cfg-if v1.0.0
Compiling ppv-lite86 v0.2.10
Compiling rand_chacha v0.3.0
Compiling rand v0.8.3
Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
Finished dev [unoptimized + debuginfo] target(s) in 2.53s
</code></pre>
<p><span class="caption">Listing 2-2: The output from running <code>cargo build</code> after
adding the rand crate as a dependency</span></p>
<p>You may see different version numbers (but they will all be compatible with
the code, thanks to SemVer!), different lines (depending on the operating
system), and the lines may be in a different order.</p>
<p>Now that we have an external dependency, Cargo fetches the latest versions of
everything from the <em>registry</em>, which is a copy of data from
<a href="https://crates.io/">Crates.io</a>. Crates.io is where people in the Rust ecosystem post
their open source Rust projects for others to use.</p>
<p>After updating the registry, Cargo checks the <code>[dependencies]</code> section and
downloads any crates you don’t have yet. In this case, although we only listed
<code>rand</code> as a dependency, Cargo also grabbed other crates that <code>rand</code> depends on
to work. After downloading the crates, Rust compiles them and then compiles the
project with the dependencies available.</p>
<p>If you immediately run <code>cargo build</code> again without making any changes, you
won’t get any output aside from the <code>Finished</code> line. Cargo knows it has already
downloaded and compiled the dependencies, and you haven’t changed anything
about them in your <em>Cargo.toml</em> file. Cargo also knows that you haven’t changed
anything about your code, so it doesn’t recompile that either. With nothing to
do, it simply exits.</p>
<p>If you open up the <em>src/main.rs</em> file, make a trivial change, and then save it
and build again, you’ll only see two lines of output:</p>
<!-- manual-regeneration
cd listings/ch02-guessing-game-tutorial/listing-02-02/
touch src/main.rs
cargo build -->
<pre><code class="language-console">$ cargo build
Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
Finished dev [unoptimized + debuginfo] target(s) in 2.53 secs
</code></pre>
<p>These lines show Cargo only updates the build with your tiny change to the
<em>src/main.rs</em> file. Your dependencies haven’t changed, so Cargo knows it can
reuse what it has already downloaded and compiled for those. It just rebuilds
your part of the code.</p>
<h4 id="ensuring-reproducible-builds-with-the-cargolock-file"><a class="header" href="#ensuring-reproducible-builds-with-the-cargolock-file">Ensuring Reproducible Builds with the <em>Cargo.lock</em> File</a></h4>
<p>Cargo has a mechanism that ensures you can rebuild the same artifact every time
you or anyone else builds your code: Cargo will use only the versions of the
dependencies you specified until you indicate otherwise. For example, what
happens if next week version 0.8.4 of the <code>rand</code> crate comes out, and that
version contains an important bug fix, but it also contains a regression that
will break your code?</p>
<p>The answer to this problem is the <em>Cargo.lock</em> file, which was created the
first time you ran <code>cargo build</code> and is now in your <em>guessing_game</em> directory.
When you build a project for the first time, Cargo figures out all the
versions of the dependencies that fit the criteria and then writes them to
the <em>Cargo.lock</em> file. When you build your project in the future, Cargo will
see that the <em>Cargo.lock</em> file exists and use the versions specified there
rather than doing all the work of figuring out versions again. This lets you
have a reproducible build automatically. In other words, your project will
remain at <code>0.8.3</code> until you explicitly upgrade, thanks to the <em>Cargo.lock</em>
file.</p>
<h4 id="updating-a-crate-to-get-a-new-version"><a class="header" href="#updating-a-crate-to-get-a-new-version">Updating a Crate to Get a New Version</a></h4>
<p>When you <em>do</em> want to update a crate, Cargo provides another command, <code>update</code>,
which will ignore the <em>Cargo.lock</em> file and figure out all the latest versions
that fit your specifications in <em>Cargo.toml</em>. If that works, Cargo will write
those versions to the <em>Cargo.lock</em> file.</p>
<p>But by default, Cargo will only look for versions greater than <code>0.8.3</code> and less
than <code>0.9.0</code>. If the <code>rand</code> crate has released two new versions, <code>0.8.4</code> and
<code>0.9.0</code>, you would see the following if you ran <code>cargo update</code>:</p>
<!-- manual-regeneration
cd listings/ch02-guessing-game-tutorial/listing-02-02/
cargo update
assuming there is a new 0.8.x version of rand; otherwise use another update
as a guide to creating the hypothetical output shown here -->
<pre><code class="language-console">$ cargo update
Updating crates.io index
Updating rand v0.8.3 -> v0.8.4
</code></pre>
<p>At this point, you would also notice a change in your <em>Cargo.lock</em> file noting
that the version of the <code>rand</code> crate you are now using is <code>0.8.4</code>.</p>
<p>If you wanted to use <code>rand</code> version <code>0.9.0</code> or any version in the <code>0.9.x</code>
series, you’d have to update the <em>Cargo.toml</em> file to look like this instead:</p>
<pre><code class="language-toml">[dependencies]
rand = "0.9.0"
</code></pre>
<p>The next time you run <code>cargo build</code>, Cargo will update the registry of crates
available and reevaluate your <code>rand</code> requirements according to the new version
you have specified.</p>
<p>There’s a lot more to say about <a href="http://doc.crates.io">Cargo</a><!-- ignore --> and <a href="http://doc.crates.io/crates-io.html">its
ecosystem</a><!-- ignore --> which we’ll discuss in Chapter 14, but
for now, that’s all you need to know. Cargo makes it very easy to reuse
libraries, so Rustaceans are able to write smaller projects that are assembled
from a number of packages.</p>
<h3 id="generating-a-random-number"><a class="header" href="#generating-a-random-number">Generating a Random Number</a></h3>
<p>Now that you’ve added the <code>rand</code> crate to <em>Cargo.toml</em>, let’s start using
<code>rand</code>. The next step is to update <em>src/main.rs</em>, as shown in Listing 2-3.</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore">use std::io;
use rand::Rng;
fn main() {
println!("Guess the number!");
let secret_number = rand::thread_rng().gen_range(1..101);
println!("The secret number is: {}", secret_number);
println!("Please input your guess.");
let mut guess = String::new();
io::stdin()
.read_line(&mut guess)
.expect("Failed to read line");
println!("You guessed: {}", guess);
}
</code></pre>
<p><span class="caption">Listing 2-3: Adding code to generate a random
number</span></p>
<p>First, we add a <code>use</code> line: <code>use rand::Rng</code>. The <code>Rng</code> trait defines
methods that random number generators implement, and this trait must be in
scope for us to use those methods. Chapter 10 will cover traits in detail.</p>
<p>Next, we’re adding two lines in the middle. The <code>rand::thread_rng</code> function
will give us the particular random number generator that we’re going to use:
one that is local to the current thread of execution and seeded by the
operating system. Then we call the <code>gen_range</code> method on the random number
generator. This method is defined by the <code>Rng</code> trait that we brought into scope
with the <code>use rand::Rng</code> statement. The <code>gen_range</code> method takes a range
expression as an argument and generates a random number in the range. The kind
of range expression we’re using here takes the form <code>start..end</code>. It’s
inclusive on the lower bound but exclusive on the upper bound, so we need to
specify <code>1..101</code> to request a number between 1 and 100. Alternatively, we could
pass the range <code>1..=100</code>, which is equivalent.</p>
<blockquote>
<p>Note: You won’t just know which traits to use and which methods and functions
to call from a crate. Instructions for using a crate are in each crate’s
documentation. Another neat feature of Cargo is that you can run the <code>cargo doc --open</code> command, which will build documentation provided by all of your
dependencies locally and open it in your browser. If you’re interested in
other functionality in the <code>rand</code> crate, for example, run <code>cargo doc --open</code>
and click <code>rand</code> in the sidebar on the left.</p>
</blockquote>
<p>The second line that we added to the middle of the code prints the secret
number. This is useful while we’re developing the program to be able to test
it, but we’ll delete it from the final version. It’s not much of a game if the
program prints the answer as soon as it starts!</p>
<p>Try running the program a few times:</p>
<!-- manual-regeneration
cd listings/ch02-guessing-game-tutorial/listing-02-03/
cargo run
4
cargo run
5
-->
<pre><code class="language-console">$ cargo run
Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
Finished dev [unoptimized + debuginfo] target(s) in 2.53s
Running `target/debug/guessing_game`
Guess the number!
The secret number is: 7
Please input your guess.
4
You guessed: 4
$ cargo run
Finished dev [unoptimized + debuginfo] target(s) in 0.02s
Running `target/debug/guessing_game`
Guess the number!
The secret number is: 83
Please input your guess.
5
You guessed: 5
</code></pre>
<p>You should get different random numbers, and they should all be numbers between
1 and 100. Great job!</p>
<h2 id="comparing-the-guess-to-the-secret-number"><a class="header" href="#comparing-the-guess-to-the-secret-number">Comparing the Guess to the Secret Number</a></h2>
<p>Now that we have user input and a random number, we can compare them. That step
is shown in Listing 2-4. Note that this code won’t compile quite yet, as we
will explain.</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore does_not_compile">use rand::Rng;
use std::cmp::Ordering;
use std::io;
fn main() {
// --snip--
<span class="boring"> println!("Guess the number!");
</span><span class="boring">
</span><span class="boring"> let secret_number = rand::thread_rng().gen_range(1..101);
</span><span class="boring">
</span><span class="boring"> println!("The secret number is: {}", secret_number);
</span><span class="boring">
</span><span class="boring"> println!("Please input your guess.");
</span><span class="boring">
</span><span class="boring"> let mut guess = String::new();
</span><span class="boring">
</span><span class="boring"> io::stdin()
</span><span class="boring"> .read_line(&mut guess)
</span><span class="boring"> .expect("Failed to read line");
</span>
println!("You guessed: {}", guess);
match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => println!("You win!"),
}
}
</code></pre>
<p><span class="caption">Listing 2-4: Handling the possible return values of
comparing two numbers</span></p>
<p>The first new bit here is another <code>use</code> statement, bringing a type called
<code>std::cmp::Ordering</code> into scope from the standard library. Like <code>Result</code>,
<code>Ordering</code> is another enum, but the variants for <code>Ordering</code> are <code>Less</code>,
<code>Greater</code>, and <code>Equal</code>. These are the three outcomes that are possible when you
compare two values.</p>
<p>Then we add five new lines at the bottom that use the <code>Ordering</code> type. The
<code>cmp</code> method compares two values and can be called on anything that can be
compared. It takes a reference to whatever you want to compare with: here it’s
comparing the <code>guess</code> to the <code>secret_number</code>. Then it returns a variant of the
<code>Ordering</code> enum we brought into scope with the <code>use</code> statement. We use a
<a href="ch06-02-match.html"><code>match</code></a><!-- ignore --> expression to decide what to do next based on
which variant of <code>Ordering</code> was returned from the call to <code>cmp</code> with the values
in <code>guess</code> and <code>secret_number</code>.</p>
<p>A <code>match</code> expression is made up of <em>arms</em>. An arm consists of a <em>pattern</em> and
the code that should be run if the value given to the beginning of the <code>match</code>
expression fits that arm’s pattern. Rust takes the value given to <code>match</code> and
looks through each arm’s pattern in turn. The <code>match</code> construct and patterns
are powerful features in Rust that let you express a variety of situations your
code might encounter and make sure that you handle them all. These features
will be covered in detail in Chapter 6 and Chapter 18, respectively.</p>
<p>Let’s walk through an example of what would happen with the <code>match</code> expression
used here. Say that the user has guessed 50 and the randomly generated secret
number this time is 38. When the code compares 50 to 38, the <code>cmp</code> method will
return <code>Ordering::Greater</code>, because 50 is greater than 38. The <code>match</code>
expression gets the <code>Ordering::Greater</code> value and starts checking each arm’s
pattern. It looks at the first arm’s pattern, <code>Ordering::Less</code>, and sees that
the value <code>Ordering::Greater</code> does not match <code>Ordering::Less</code>, so it ignores
the code in that arm and moves to the next arm. The next arm’s pattern,
<code>Ordering::Greater</code>, <em>does</em> match <code>Ordering::Greater</code>! The associated code in
that arm will execute and print <code>Too big!</code> to the screen. The <code>match</code>
expression ends because it has no need to look at the last arm in this scenario.</p>
<p>However, the code in Listing 2-4 won’t compile yet. Let’s try it:</p>
<pre><code class="language-console">$ cargo build
Compiling libc v0.2.86
Compiling getrandom v0.2.2
Compiling cfg-if v1.0.0
Compiling ppv-lite86 v0.2.10
Compiling rand_core v0.6.2
Compiling rand_chacha v0.3.0
Compiling rand v0.8.3
Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
error[E0308]: mismatched types
--> src/main.rs:22:21
|
22 | match guess.cmp(&secret_number) {
| ^^^^^^^^^^^^^^ expected struct `String`, found integer
|
= note: expected reference `&String`
found reference `&{integer}`
error: aborting due to previous error
For more information about this error, try `rustc --explain E0308`.
error: could not compile `guessing_game`
To learn more, run the command again with --verbose.
</code></pre>
<p>The core of the error states that there are <em>mismatched types</em>. Rust has a
strong, static type system. However, it also has type inference. When we wrote
<code>let mut guess = String::new()</code>, Rust was able to infer that <code>guess</code> should be
a <code>String</code> and didn’t make us write the type. The <code>secret_number</code>, on the other
hand, is a number type. A few number types can have a value between 1 and 100:
<code>i32</code>, a 32-bit number; <code>u32</code>, an unsigned 32-bit number; <code>i64</code>, a 64-bit
number; as well as others. Rust defaults to an <code>i32</code>, which is the type of
<code>secret_number</code> unless you add type information elsewhere that would cause Rust
to infer a different numerical type. The reason for the error is that Rust
cannot compare a string and a number type.</p>
<p>Ultimately, we want to convert the <code>String</code> the program reads as input into a
real number type so we can compare it numerically to the secret number. We can
do that by adding another line to the <code>main</code> function body:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore"><span class="boring">use rand::Rng;
</span><span class="boring">use std::cmp::Ordering;
</span><span class="boring">use std::io;
</span><span class="boring">
</span><span class="boring">fn main() {
</span><span class="boring"> println!("Guess the number!");
</span><span class="boring">
</span><span class="boring"> let secret_number = rand::thread_rng().gen_range(1..101);
</span><span class="boring">
</span><span class="boring"> println!("The secret number is: {}", secret_number);
</span><span class="boring">
</span><span class="boring"> println!("Please input your guess.");
</span><span class="boring">
</span> // --snip--
let mut guess = String::new();
io::stdin()
.read_line(&mut guess)
.expect("Failed to read line");
let guess: u32 = guess.trim().parse().expect("Please type a number!");
println!("You guessed: {}", guess);
match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => println!("You win!"),
}
<span class="boring">}
</span></code></pre>
<p>The line is:</p>
<pre><code class="language-rust ignore">let guess: u32 = guess.trim().parse().expect("Please type a number!");
</code></pre>
<p>We create a variable named <code>guess</code>. But wait, doesn’t the program already have
a variable named <code>guess</code>? It does, but Rust allows us to <em>shadow</em> the previous
value of <code>guess</code> with a new one. This feature is often used in situations in
which you want to convert a value from one type to another type. Shadowing lets
us reuse the <code>guess</code> variable name rather than forcing us to create two unique
variables, such as <code>guess_str</code> and <code>guess</code> for example. (Chapter 3 covers
shadowing in more detail.)</p>
<p>We bind <code>guess</code> to the expression <code>guess.trim().parse()</code>. The <code>guess</code> in the
expression refers to the original <code>guess</code> that was a <code>String</code> with the input in
it. The <code>trim</code> method on a <code>String</code> instance will eliminate any whitespace at
the beginning and end. Although <code>u32</code> can contain only numerical characters,
the user must press <span class="keystroke">enter</span> to satisfy
<code>read_line</code>. When the user presses <span class="keystroke">enter</span>, a
newline character is added to the string. For example, if the user types <span
class="keystroke">5</span> and presses <span class="keystroke">enter</span>,
<code>guess</code> looks like this: <code>5\n</code>. The <code>\n</code> represents “newline,” the result of
pressing <span class="keystroke">enter</span> (On Windows, pressing <span
class="keystroke">enter</span> results in a carriage return and a newline,
<code>\r\n</code>). The <code>trim</code> method eliminates <code>\n</code> or <code>\r\n</code>, resulting in just <code>5</code>.</p>
<p>The <a href="../std/primitive.str.html#method.parse"><code>parse</code> method on strings</a><!-- ignore --> parses a string into some
kind of number. Because this method can parse a variety of number types, we
need to tell Rust the exact number type we want by using <code>let guess: u32</code>. The
colon (<code>:</code>) after <code>guess</code> tells Rust we’ll annotate the variable’s type. Rust
has a few built-in number types; the <code>u32</code> seen here is an unsigned, 32-bit
integer. It’s a good default choice for a small positive number. You’ll learn
about other number types in Chapter 3. Additionally, the <code>u32</code> annotation in
this example program and the comparison with <code>secret_number</code> means that Rust
will infer that <code>secret_number</code> should be a <code>u32</code> as well. So now the
comparison will be between two values of the same type!</p>
<p>The call to <code>parse</code> could easily cause an error. If, for example, the string
contained <code>A👍%</code>, there would be no way to convert that to a number. Because it
might fail, the <code>parse</code> method returns a <code>Result</code> type, much as the <code>read_line</code>
method does (discussed earlier in <a href="#handling-potential-failure-with-the-result-type">“Handling Potential Failure with the
<code>Result</code> Type”</a><!-- ignore
-->). We’ll treat this <code>Result</code> the same way by using the <code>expect</code> method
again. If <code>parse</code> returns an <code>Err</code> <code>Result</code> variant because it couldn’t create
a number from the string, the <code>expect</code> call will crash the game and print the
message we give it. If <code>parse</code> can successfully convert the string to a number,
it will return the <code>Ok</code> variant of <code>Result</code>, and <code>expect</code> will return the
number that we want from the <code>Ok</code> value.</p>
<p>Let’s run the program now!</p>
<!-- manual-regeneration
cd listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/
cargo run
76
-->
<pre><code class="language-console">$ cargo run
Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
Finished dev [unoptimized + debuginfo] target(s) in 0.43s
Running `target/debug/guessing_game`
Guess the number!
The secret number is: 58
Please input your guess.
76
You guessed: 76
Too big!
</code></pre>
<p>Nice! Even though spaces were added before the guess, the program still figured
out that the user guessed 76. Run the program a few times to verify the
different behavior with different kinds of input: guess the number correctly,
guess a number that is too high, and guess a number that is too low.</p>
<p>We have most of the game working now, but the user can make only one guess.
Let’s change that by adding a loop!</p>
<h2 id="allowing-multiple-guesses-with-looping"><a class="header" href="#allowing-multiple-guesses-with-looping">Allowing Multiple Guesses with Looping</a></h2>
<p>The <code>loop</code> keyword creates an infinite loop. We’ll add that now to give users
more chances at guessing the number:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore"><span class="boring">use rand::Rng;
</span><span class="boring">use std::cmp::Ordering;
</span><span class="boring">use std::io;
</span><span class="boring">
</span><span class="boring">fn main() {
</span><span class="boring"> println!("Guess the number!");
</span><span class="boring">
</span><span class="boring"> let secret_number = rand::thread_rng().gen_range(1..101);
</span><span class="boring">
</span> // --snip--
println!("The secret number is: {}", secret_number);
loop {
println!("Please input your guess.");
// --snip--
<span class="boring">
</span><span class="boring"> let mut guess = String::new();
</span><span class="boring">
</span><span class="boring"> io::stdin()
</span><span class="boring"> .read_line(&mut guess)
</span><span class="boring"> .expect("Failed to read line");
</span><span class="boring">
</span><span class="boring"> let guess: u32 = guess.trim().parse().expect("Please type a number!");
</span><span class="boring">
</span><span class="boring"> println!("You guessed: {}", guess);
</span><span class="boring">
</span> match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => println!("You win!"),
}
}
}
</code></pre>
<p>As you can see, we’ve moved everything into a loop from the guess input prompt
onward. Be sure to indent the lines inside the loop another four spaces each
and run the program again. Notice that there is a new problem because the
program is doing exactly what we told it to do: ask for another guess forever!
It doesn’t seem like the user can quit!</p>
<p>The user could always interrupt the program by using the keyboard shortcut <span
class="keystroke">ctrl-c</span>. But there’s another way to escape this
insatiable monster, as mentioned in the <code>parse</code> discussion in <a href="#comparing-the-guess-to-the-secret-number">“Comparing the
Guess to the Secret Number”</a><!--
ignore -->: if the user enters a non-number answer, the program will crash. The
user can take advantage of that in order to quit, as shown here:</p>
<!-- manual-regeneration
cd listings/ch02-guessing-game-tutorial/no-listing-04-looping/
cargo run
(too small guess)
(too big guess)
(correct guess)
quit
-->
<pre><code class="language-console">$ cargo run
Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
Finished dev [unoptimized + debuginfo] target(s) in 1.50s
Running `target/debug/guessing_game`
Guess the number!
The secret number is: 59
Please input your guess.
45
You guessed: 45
Too small!
Please input your guess.
60
You guessed: 60