book

Programming Rust, 2nd Edition

by Jim Blandy, Jason Orendorff, Leonora F. S. Tindall

June 2021

Intermediate to advanced

738 pages

18h 47m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Includes

Has Sandbox

Who Should Read This BookWhy We Wrote This BookNavigating This BookConventions Used in This BookUsing Code ExamplesO’Reilly Online LearningHow to Contact UsAcknowledgments
Rust Shoulders the Load for YouParallel Programming Is TamedAnd Yet Rust Is Still FastRust Makes Collaboration Easier
rustup and CargoRust FunctionsWriting and Running Unit TestsHandling Command-Line ArgumentsServing Pages to the WebConcurrencyWhat 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 InvisibleFilesystems and Command-Line ToolsThe Command-Line InterfaceReading and Writing FilesFind and Replace
Fixed-Width Numeric TypesInteger TypesChecked, Wrapping, Saturating, and Overflowing ArithmeticFloating-Point TypesThe bool TypeCharactersTuplesPointer TypesReferencesBoxesRaw PointersArrays, Vectors, and SlicesArraysVectorsSlicesString TypesString LiteralsByte StringsStrings in MemoryStringUsing StringsOther String-Like TypesType AliasesBeyond the Basics
OwnershipMovesMore Operations That MoveMoves and Control FlowMoves and Indexed ContentCopy Types: The Exception to MovesRc and Arc: Shared Ownership
References to ValuesWorking with ReferencesRust 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 Function ArgumentsPassing References to FunctionsReturning ReferencesStructs Containing ReferencesDistinct Lifetime ParametersOmitting Lifetime ParametersSharing Versus MutationTaking Arms Against a Sea of Objects
An Expression LanguagePrecedence and AssociativityBlocks and SemicolonsDeclarationsif and matchif letLoopsControl Flow in Loopsreturn ExpressionsWhy Rust Has loopFunction and Method CallsFields and ElementsReference OperatorsArithmetic, Bitwise, Comparison, and Logical OperatorsAssignmentType CastsClosuresOnward
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?
CratesEditionsBuild ProfilesModulesNested ModulesModules in Separate FilesPaths and ImportsThe Standard PreludeMaking use Declarations pubMaking Struct Fields pubStatics and ConstantsTurning 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 implPassing Self as a Box, Rc, or ArcType-Associated FunctionsAssociated ConstsGeneric StructsGeneric Structs with Lifetime ParametersGeneric Structs with Constant ParametersDeriving Common Traits for Struct TypesInterior Mutability

EnumsEnums with DataEnums in MemoryRich Data Structures Using EnumsGeneric EnumsPatternsLiterals, Variables, and Wildcards in PatternsTuple and Struct PatternsArray and Slice PatternsReference PatternsMatch GuardsMatching Multiple PossibilitiesBinding with @ PatternsWhere Patterns Are AllowedPopulating a Binary TreeThe Big Picture
Using TraitsTrait ObjectsGeneric Functions and Type ParametersWhich to UseDefining and Implementing TraitsDefault MethodsTraits and Other People’s TypesSelf in TraitsSubtraitsType-Associated FunctionsFully Qualified Method CallsTraits That Define Relationships Between TypesAssociated Types (or How Iterators Work)Generic Traits (or How Operator Overloading Works)impl TraitAssociated ConstsReverse-Engineering BoundsTraits as a Foundation
Arithmetic and Bitwise OperatorsUnary OperatorsBinary OperatorsCompound Assignment OperatorsEquivalence ComparisonsOrdered ComparisonsIndex and IndexMutOther Operators
DropSizedCloneCopyDeref and DerefMutDefaultAsRef and AsMutBorrow and BorrowMutFrom and IntoTryFrom and TryIntoToOwnedBorrow and ToOwned at Work: The Humble Cow
Capturing VariablesClosures That BorrowClosures That StealFunction and Closure TypesClosure PerformanceClosures and SafetyClosures That KillFnOnceFnMutCopy and Clone for ClosuresCallbacksUsing Closures Effectively
The Iterator and IntoIterator TraitsCreating Iteratorsiter and iter_mut MethodsIntoIterator Implementationsfrom_fn and successorsdrain MethodsOther Iterator SourcesIterator Adaptersmap and filterfilter_map and flat_mapflattentake and take_whileskip and skip_whilepeekablefuseReversible Iterators and revinspectchainenumeratezipby_refcloned, copiedcycleConsuming IteratorsSimple Accumulation: count, sum, productmax, minmax_by, min_bymax_by_key, min_by_keyComparing Item Sequencesany and allposition, rposition, and ExactSizeIteratorfold and rfoldtry_fold and try_rfoldnth, nth_backlastfind, rfind, and find_mapBuilding Collections: collect and FromIteratorThe Extend Traitpartitionfor_each and try_for_eachImplementing Your Own Iterators
OverviewVec<T>Accessing ElementsIterationGrowing and Shrinking VectorsJoiningSplittingSwappingFillingSorting and SearchingComparing SlicesRandom ElementsRust Rules Out Invalidation ErrorsVecDeque<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 and Replacing 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 MutexesMulticonsumer Channels Using MutexesRead/Write Locks (RwLock<T>)Condition Variables (Condvar)AtomicsGlobal VariablesWhat Hacking Concurrent Code in Rust Is Like
From Synchronous to AsynchronousFuturesAsync Functions and Await ExpressionsCalling Async Functions from Synchronous Code: block_onSpawning Async TasksAsync BlocksBuilding Async Functions from Async BlocksSpawning Async Tasks on a Thread PoolBut Does Your Future Implement Send?Long Running Computations: yield_now and spawn_blockingComparing Asynchronous DesignsA Real Asynchronous HTTP ClientAn Asynchronous Client and ServerError and Result TypesThe ProtocolTaking User Input: Asynchronous StreamsSending PacketsReceiving Packets: More Asynchronous StreamsThe Client’s Main FunctionThe Server’s Main FunctionHandling Chat Connections: Async MutexesThe Group Table: Synchronous MutexesChat Groups: tokio’s Broadcast ChannelsPrimitive Futures and Executors: When Is a Future Worth Polling Again?Invoking Wakers: spawn_blockingImplementing block_onPinningThe Two Life Stages of a FuturePinned PointersThe Unpin TraitWhen Is Asynchronous Code Helpful?
Macro BasicsBasics of Macro ExpansionUnintended ConsequencesRepetitionBuilt-In MacrosDebugging MacrosBuilding the 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 CodeReinterpreting Memory with UnionsMatching UnionsBorrowing Unions
Finding Common Data RepresentationsDeclaring Foreign Functions and VariablesUsing Functions from LibrariesA Raw Interface to libgit2A Safe Interface to libgit2Conclusion

Content preview from Programming Rust, 2nd Edition

Chapter 8. Crates and Modules

This is one note in a Rust theme: systems programmers can have nice things.

Robert O’Callahan, “Random Thoughts on Rust: crates.io and IDEs”

Suppose you’re writing a program that simulates the growth of ferns, from the level of individual cells on up. Your program, like a fern, will start out very simple, with all the code, perhaps, in a single file—just the spore of an idea. As it grows, it will start to have internal structure. Different pieces will have different purposes. It will branch out into multiple files. It may cover a whole directory tree. In time it may become a significant part of a whole software ecosystem. For any program that grows beyond a few data structures or a few hundred lines, some organization is necessary.

This chapter covers the features of Rust that help keep your program organized: crates and modules. We’ll also cover other topics related to the structure and distribution of a Rust crate, including how to document and test Rust code, how to silence unwanted compiler warnings, how to use Cargo to manage project dependencies and versioning, how to publish open source libraries on Rust’s public crate repository, crates.io, how Rust evolves through language editions, and more, using the fern simulator as our running example.

Crates

Rust programs are made of crates. Each crate is a complete, cohesive unit: all the source code for a single library or executable, plus any associated tests, examples, tools, configuration, and ...