book

Programming Rust

by Jim Blandy, Jason Orendorff

December 2017

Intermediate to advanced

619 pages

15h 11m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Who Should Read This BookWhy We Wrote This BookNavigating This BookConventions Used in This BookUsing Code ExamplesO’Reilly SafariHow to Contact UsAcknowledgments
Type Safety
Downloading and Installing RustA Simple FunctionWriting and Running Unit TestsHandling Command-Line ArgumentsA Simple Web ServerConcurrencyWhat the Mandelbrot Set Actually IsParsing Pair Command-Line ArgumentsMapping from Pixels to Complex NumbersPlotting the SetWriting Image FilesA Concurrent Mandelbrot ProgramRunning the Mandelbrot PlotterSafety Is Invisible
Machine TypesInteger TypesFloating-Point TypesThe bool TypeCharactersTuplesPointer TypesReferencesBoxesRaw PointersArrays, Vectors, and SlicesArraysVectorsSlicesString TypesString LiteralsByte StringsStrings in MemoryStringUsing StringsOther String-Like TypesBeyond the Basics
OwnershipMovesMore Operations That MoveMoves and Control FlowMoves and Indexed ContentCopy Types: The Exception to MovesRc and Arc: Shared Ownership
References as ValuesRust References Versus C++ ReferencesAssigning ReferencesReferences to ReferencesComparing ReferencesReferences Are Never NullBorrowing References to Arbitrary ExpressionsReferences to Slices and Trait ObjectsReference SafetyBorrowing a Local VariableReceiving References as ParametersPassing References as ArgumentsReturning ReferencesStructs Containing ReferencesDistinct Lifetime ParametersOmitting Lifetime ParametersSharing Versus MutationTaking Arms Against a Sea of Objects
An Expression LanguageBlocks and SemicolonsDeclarationsif and matchif letLoopsreturn ExpressionsWhy Rust Has loopFunction and Method CallsFields and ElementsReference OperatorsArithmetic, Bitwise, Comparison, and Logical OperatorsAssignmentType CastsClosuresPrecedence and AssociativityOnward
PanicUnwindingAbortingResultCatching ErrorsResult Type AliasesPrinting ErrorsPropagating ErrorsWorking with Multiple Error TypesDealing with Errors That “Can’t Happen”Ignoring ErrorsHandling Errors in main()Declaring a Custom Error TypeWhy Results?
CratesBuild ProfilesModulesModules in Separate FilesPaths and ImportsThe Standard PreludeItems, the Building Blocks of RustTurning a Program into a LibraryThe src/bin DirectoryAttributesTests and DocumentationIntegration TestsDocumentationDoc-TestsSpecifying DependenciesVersionsCargo.lockPublishing Crates to crates.ioWorkspacesMore Nice Things
Named-Field StructsTuple-Like StructsUnit-Like StructsStruct LayoutDefining Methods with implGeneric StructsStructs with Lifetime ParametersDeriving Common Traits for Struct TypesInterior Mutability

EnumsEnums with DataEnums in MemoryRich Data Structures Using EnumsGeneric EnumsPatternsLiterals, Variables, and Wildcards in PatternsTuple and Struct PatternsReference PatternsMatching Multiple PossibilitiesPattern Guards@ patternsWhere Patterns Are AllowedPopulating a Binary TreeThe Big Picture
Using TraitsTrait ObjectsTrait Object LayoutGeneric FunctionsWhich to UseDefining and Implementing TraitsDefault MethodsTraits and Other People’s TypesSelf in TraitsSubtraitsStatic MethodsFully Qualified Method CallsTraits That Define Relationships Between TypesAssociated Types (or How Iterators Work)Generic Traits (or How Operator Overloading Works)Buddy Traits (or How rand::random() Works)Reverse-Engineering BoundsConclusion
Arithmetic and Bitwise OperatorsUnary OperatorsBinary OperatorsCompound Assignment OperatorsEquality TestsOrdered ComparisonsIndex and IndexMutOther Operators
DropSizedCloneCopyDeref and DerefMutDefaultAsRef and AsMutBorrow and BorrowMutFrom and IntoToOwnedBorrow and ToOwned at Work: The Humble Cow
Capturing VariablesClosures That BorrowClosures That StealFunction and Closure TypesClosure PerformanceClosures and SafetyClosures That KillFnOnceFnMutCallbacksUsing Closures Effectively
The Iterator and IntoIterator TraitsCreating Iteratorsiter and iter_mut MethodsIntoIterator Implementationsdrain MethodsOther Iterator SourcesIterator Adaptersmap and filterfilter_map and flat_mapscantake and take_whileskip and skip_whilepeekablefuseReversible Iterators and revinspectchainenumeratezipby_refclonedcycleConsuming IteratorsSimple Accumulation: count, sum, productmax, minmax_by, min_bymax_by_key, min_by_keyComparing Item Sequencesany and allposition, rposition, and ExactSizeIteratorfoldnthlastfindBuilding Collections: collect and FromIteratorThe Extend TraitpartitionImplementing Your Own Iterators
OverviewVec<T>Accessing ElementsIterationGrowing and Shrinking VectorsJoiningSplittingSwappingSorting and SearchingComparing SlicesRandom ElementsRust Rules Out Invalidation ErrorsVecDeque<T>LinkedList<T>BinaryHeap<T>HashMap<K, V> and BTreeMap<K, V>EntriesMap IterationHashSet<T> and BTreeSet<T>Set IterationWhen Equal Values Are DifferentWhole-Set OperationsHashingUsing a Custom Hashing AlgorithmBeyond the Standard Collections
Some Unicode BackgroundASCII, Latin-1, and UnicodeUTF-8Text DirectionalityCharacters (char)Classifying CharactersHandling DigitsCase Conversion for CharactersConversions to and from IntegersString and strCreating String ValuesSimple InspectionAppending and Inserting TextRemoving TextConventions for Searching and IteratingPatterns for Searching TextSearching and ReplacingIterating over TextTrimmingCase Conversion for StringsParsing Other Types from StringsConverting Other Types to StringsBorrowing as Other Text-Like TypesAccessing Text as UTF-8Producing Text from UTF-8 DataPutting Off AllocationStrings as Generic CollectionsFormatting ValuesFormatting Text ValuesFormatting NumbersFormatting Other TypesFormatting Values for DebuggingFormatting Pointers for DebuggingReferring to Arguments by Index or NameDynamic Widths and PrecisionsFormatting Your Own TypesUsing the Formatting Language in Your Own CodeRegular ExpressionsBasic Regex UseBuilding Regex Values LazilyNormalizationNormalization FormsThe unicode-normalization Crate
Readers and WritersReadersBuffered ReadersReading LinesCollecting LinesWritersFilesSeekingOther Reader and Writer TypesBinary Data, Compression, and SerializationFiles and DirectoriesOsStr and PathPath and PathBuf MethodsFilesystem Access FunctionsReading DirectoriesPlatform-Specific FeaturesNetworking
Fork-Join Parallelismspawn and joinError Handling Across ThreadsSharing Immutable Data Across ThreadsRayonRevisiting the Mandelbrot SetChannelsSending ValuesReceiving ValuesRunning the PipelineChannel Features and PerformanceThread Safety: Send and SyncPiping Almost Any Iterator to a ChannelBeyond PipelinesShared Mutable StateWhat Is a Mutex?Mutex<T>mut and MutexWhy Mutexes Are Not Always a Good IdeaDeadlockPoisoned MutexesMulti-Consumer Channels Using MutexesRead/Write Locks (RwLock<T>)Condition Variables (Condvar)AtomicsGlobal VariablesWhat Hacking Concurrent Code in Rust Is Like
Macro BasicsBasics of Macro ExpansionUnintended ConsequencesRepetitionBuilt-In MacrosDebugging MacrosThe json! MacroFragment TypesRecursion in MacrosUsing Traits with MacrosScoping and HygieneImporting and Exporting MacrosAvoiding Syntax Errors During MatchingBeyond macro_rules!
Unsafe from What?Unsafe BlocksExample: An Efficient ASCII String TypeUnsafe FunctionsUnsafe Block or Unsafe Function?Undefined BehaviorUnsafe TraitsRaw PointersDereferencing Raw Pointers SafelyExample: RefWithFlagNullable PointersType Sizes and AlignmentsPointer ArithmeticMoving into and out of MemoryExample: GapBufferPanic Safety in Unsafe CodeForeign Functions: Calling C and C++ from RustFinding Common Data RepresentationsDeclaring Foreign Functions and VariablesUsing Functions from LibrariesA Raw Interface to libgit2A Safe Interface to libgit2Conclusion

Content preview from Programming Rust

Chapter 4. Ownership

I’ve found that Rust has forced me to learn many of the things that I was slowly learning as ‘good practice’ in C/C++ before I could even compile my code. ...I want to stress that Rust isn’t the kind of language you can learn in a couple days and just deal with the hard/technical/good-practice stuff later. You will be forced to learn strict safety immediately and it will probably feel uncomfortable at first. However in my own experience, this has led me towards feeling like compiling my code actually means something to me again.

Mitchell Nordine

Rust makes the following pair of promises, both essential to a safe systems programming language:

You decide the lifetime of each value in your program. Rust frees memory and other resources belonging to a value promptly, at a point under your control.
Even so, your program will never use a pointer to an object after it has been freed. Using a dangling pointer is a common mistake in C and C++: if you’re lucky, your program crashes. If you’re unlucky, your program has a security hole. Rust catches these mistakes at compile time.

C and C++ keep the first promise: you can call free or delete on any object in the dynamically allocated heap you like, whenever you like. But in exchange, the second promise is set aside: it is entirely your responsibility to ensure that no pointer to the value you freed is ever used. There’s ample empirical evidence that this is a difficult responsibility to meet: pointer misuse has ...