2. Set up your environment

1. Install theFlutter SDK.
2. Set up an editor such as Visual Studio Code (VS Code).
3. Go through thePlatform setup steps for at least one target platform (iOS, Android, Desktop, or a web browser).

3. Create the project

Before diving into patterns, records, and other new features, take a moment to create a Flutter project for which you write all your code.

Create a Flutter project

1. Use theflutter create command to create a new project namedpatterns_codelab. The--empty flag prevents the creation of the standard counter app in thelib/main.dart file, which you'd have to remove anyway.

flutter create --empty patterns_codelab

2. Then, open thepatterns_codelab directory using VS Code.

code patterns_codelab

Set the minimum SDK version

• Set the SDK version constraint for your project to depend on Dart 3 or above.

pubspec.yaml

environment:sdk:^3.0.0

6. Match and destructure with patterns

Records can efficiently collect different types of data and easily pass it around. Now, improve your code usingpatterns.

A pattern represents a structure that one or more values can take, like a blueprint. Patterns compare against actual values to determine if theymatch.

Some patterns, when they match,destructure the matched value by pulling data out of it. Destructuring lets you unpack values from an object to assign them to local variables, or perform further matching on them.

Destructure a record into local variables

1. Refactor thebuild method ofDocumentScreen to callmetadata and use it to initialize apattern variable declaration:

lib/main.dart

classDocumentScreenextendsStatelessWidget{finalDocumentdocument;constDocumentScreen({requiredthis.document,super.key});@overrideWidgetbuild(BuildContextcontext){final(title,modified:modified)=document.metadata;//ModifyreturnScaffold(appBar:AppBar(title:Text(title)),//Modifyfromhere...body:Column(children:[Center(child:Text('Last modified $modified'))]),);//Tohere.}}

The record pattern(title, modified: modified) contains twovariable patterns that match against the fields of the record returned bymetadata.

• The expression matches the subpattern because the result is a record with two fields, one of which is namedmodified.
• Because they match, the variable declaration pattern destructures the expression, accessing its values and binding them to new local variables of the same types and names,String title andDateTime modified.

There is a shorthand for when the name of a field and the variable populating it are the same. Refactor thebuild method ofDocumentScreen as follows.

lib/main.dart

classDocumentScreenextendsStatelessWidget{finalDocumentdocument;constDocumentScreen({requiredthis.document,super.key});@overrideWidgetbuild(BuildContextcontext){final(title,:modified)=document.metadata;//ModifyreturnScaffold(appBar:AppBar(title:Text(title)),body:Column(children:[Center(child:Text('Last modified $modified'))]),);}}

The syntax of the variable pattern:modified is shorthand formodified: modified. If you want a new local variable of a different name, you can writemodified: localModified instead.

2. Hot reload to see the same result as in the previous step. The behavior is exactly the same; you just made your code more concise.

7. Use patterns to extract data

In certain contexts, patterns don't only match and destructure but can also make adecision aboutwhat the code does, based on whether or not the pattern matches. These are calledrefutable patterns.

The variable declaration pattern you used in the last step is anirrefutable pattern: the value must match the pattern or it's an error and destructuring won't happen. Think of any variable declaration or assignment; you can't assign a value to a variable if they're not the same type.

Refutable patterns, on the other hand, are used in control flow contexts:

• Theyexpect that some values they compare against will not match.
• They are meant toinfluence the control flow, based on whether or not the value matches.
• Theydon't interrupt execution with an error if they don't match, they just move to the next statement.
• They can destructure and bind variables that areonly usable when they match

Read JSON values without patterns

In this section, you read data without pattern matching to see how patterns can help you work with JSON data.

• Replace the previous version ofmetadata with one that reads values from the_json map. Copy and paste this version ofmetadata into theDocument class:

lib/data.dart

classDocument{finalMap<String,Object?>_json;Document():_json=jsonDecode(documentJson);(String,{DateTimemodified})getmetadata{if(_json.containsKey('metadata')){//Modifyfromhere...finalmetadataJson=_json['metadata'];if(metadataJsonisMap){finaltitle=metadataJson['title']asString;finallocalModified=DateTime.parse(metadataJson['modified']asString,);return(title,modified:localModified);}}throwconstFormatException('Unexpected JSON');//tohere.}}

This code validates that the data is structured correctly without using patterns. In a later step, you use pattern matching to perform the same validation using less code. It performs three checks before doing anything else:

• The JSON contains the datastructure you expect:if (_json.containsKey('metadata'))
• The data has thetype you expect:if (metadataJson is Map)
• That the data isnot null, which is implicitly confirmed in the previous check.

Read JSON values using a map pattern

With a refutable pattern, you can verify that the JSON has the expected structure using amap pattern.

• Replace the previous version ofmetadata with this code:

lib/data.dart

classDocument{finalMap<String,Object?>_json;Document():_json=jsonDecode(documentJson);(String,{DateTimemodified})getmetadata{if(_jsoncase{//Modifyfromhere...'metadata':{'title':Stringtitle,'modified':StringlocalModified},}){return(title,modified:DateTime.parse(localModified));}else{throwconstFormatException('Unexpected JSON');}//tohere.}}

Here, you see a new kind of if-statement (introduced in Dart 3), theif-case. The case body only executes if the case pattern matches the data in_json. This match accomplishes the same checks you wrote in the first version ofmetadata to validate the incoming JSON. This code validates the following:

• _json is a Map type.
• _json contains ametadata key.
• _json is not null.
• _json['metadata'] is also a Map type.
• _json['metadata'] contains the keystitle andmodified.
• title andlocalModified are strings and aren't null.

If the value doesn't match, thepattern refutes (refuses to continue execution) and proceeds to theelse clause. If the match is successful, the pattern destructures the values oftitle andmodified from the map and binds them to new local variables.

For a full list of patterns, see thetable in the Patterns section of the feature specification.

9. Use patterns to display the document

You now successfully destructure and recompose your JSON data, using an if-case statement and refutable patterns. But if-case is only one of the enhancements to control flow structures that come with patterns. Now, you apply your knowledge of refutable patterns to switch statements.

Control what's rendered using patterns with switch statements

• Inmain.dart, create a new widget,BlockWidget, that determines the styling of each block based on itstype field.

lib/main.dart

classBlockWidgetextendsStatelessWidget{finalBlockblock;constBlockWidget({requiredthis.block,super.key});@overrideWidgetbuild(BuildContextcontext){TextStyle?textStyle;switch(block.type){case'h1':textStyle=Theme.of(context).textTheme.displayMedium;case'p'||'checkbox':textStyle=Theme.of(context).textTheme.bodyMedium;case_:textStyle=Theme.of(context).textTheme.bodySmall;}returnContainer(margin:constEdgeInsets.all(8),child:Text(block.text,style:textStyle),);}}

The switch statement in thebuild method switches on thetype field of theblock object.

1. The first case statement uses aconstant string pattern. The pattern matches ifblock.type is equal to the constant valueh1.
2. The second case statement uses alogical-or pattern with two constant string patterns as its subpatterns. The pattern matches ifblock.type matches either of the subpatternsp orcheckbox.

lib/main.dart

classDocumentScreenextendsStatelessWidget{finalDocumentdocument;constDocumentScreen({requiredthis.document,super.key});@overrideWidgetbuild(BuildContextcontext){final(title,:modified)=document.metadata;finalblocks=document.getBlocks();//AddthislinereturnScaffold(appBar:AppBar(title:Text(title)),body:Column(children:[Text('Last modified: $modified'),//ModifyfromhereExpanded(child:ListView.builder(itemCount:blocks.length,itemBuilder:(context,index){returnBlockWidget(block:blocks[index]);},),),//tohere.],),);}}

The lineBlockWidget(block: blocks[index]) constructs aBlockWidget widget for each item in the list of blocks returned from thegetBlocks() method.

2. Run the application, and then you should see the blocks appearing on screen:

10. Use switch expressions

Patterns add a lot of capabilities toswitch andcase. To make them usable in more places, Dart hasswitch expressions. A series of cases can provide a value directly to a variable assignment or return statement.

Convert the switch statement into a switch expression

The Dart analyzer providesassists to help you make changes to your code.

1. Move your cursor to the switch statement from the previous section.
2. Click on the lightbulb to view the available assists.
3. Select theConvert to switch expression assist.

The new version of this code looks like this:

lib/main.dart

classBlockWidgetextendsStatelessWidget{finalBlockblock;constBlockWidget({requiredthis.block,super.key});@overrideWidgetbuild(BuildContextcontext){TextStyle?textStyle;//ModifyfromheretextStyle=switch(block.type){'h1'=>Theme.of(context).textTheme.displayMedium,'p'||'checkbox'=>Theme.of(context).textTheme.bodyMedium,_=>Theme.of(context).textTheme.bodySmall,};//tohere.returnContainer(margin:constEdgeInsets.all(8),child:Text(block.text,style:textStyle),);}}

A switch expression looks similar to a switch statement, but it eliminates thecase keyword and uses=> to separate the pattern from the case body. Unlike switch statements, switch expressions return a value and can be used anywhere an expression can be used.

11. Use object patterns

Dart is an object-oriented language, so patterns apply to all objects. In this step, you switch on anobject pattern and destructure object properties to enhance the date rendering logic of your UI.

lib/main.dart

StringformatDate(DateTimedateTime){finaltoday=DateTime.now();finaldifference=dateTime.difference(today);returnswitch(difference){Duration(inDays:0)=>'today',Duration(inDays:1)=>'tomorrow',Duration(inDays:-1)=>'yesterday',Duration(inDays:finaldays,isNegative:true)=>'${days.abs()}daysago',Duration(inDays:finaldays)=>'$daysdaysfromnow',};}

This method returns a switch expression that switches on the valuedifference, aDuration object. It represents the span of time betweentoday and themodified value from the JSON data.

Each case of the switch expression is using an object pattern that matches by calling getters on the object's propertiesinDays andisNegative. The syntax looks like it might be constructing a Duration object, but it's actually accessing fields on thedifference object.

The first three cases use constant subpatterns0,1, and-1 to match the object propertyinDays and return the corresponding string.

The last two cases handle durations beyond today, yesterday, and tomorrow:

• If theisNegative property matches theboolean constant patterntrue, meaning the modification date was in the past, it displaysdays ago.
• If that case doesn't catch the difference, then duration must be a positive number of days (no need to explicitly verify withisNegative: false), so the modification date is in the future and displaysdays from now.

Add formatting logic for weeks

• Add two new cases to your formatting function in order to identify durations longer than 7 days so that the UI can display them asweeks:

lib/main.dart

StringformatDate(DateTimedateTime){finaltoday=DateTime.now();finaldifference=dateTime.difference(today);returnswitch(difference){Duration(inDays:0)=>'today',Duration(inDays:1)=>'tomorrow',Duration(inDays:-1)=>'yesterday',Duration(inDays:finaldays)whendays >7=>'${days~/7}weeksfromnow',//AddfromhereDuration(inDays:finaldays)whendays <-7=>'${days.abs()~/7}weeksago',//tohere.Duration(inDays:finaldays,isNegative:true)=>'${days.abs()}daysago',Duration(inDays:finaldays)=>'$daysdaysfromnow',};}

This code introducesguard clauses:

• A guard clause uses thewhen keyword after a case pattern.
• They can be used in if-cases, switch statements, and switch expressions.
• They only add a condition to a patternafter it's matched.
• If the guard clause evaluates to false, the entire pattern isrefuted, and execution proceeds to the next case.

Add the newly formatted date to the UI

1. Finally, update thebuild method inDocumentScreen to use theformatDate function:

lib/main.dart

classDocumentScreenextendsStatelessWidget{finalDocumentdocument;constDocumentScreen({requiredthis.document,super.key});@overrideWidgetbuild(BuildContextcontext){final(title,:modified)=document.metadata;finalformattedModifiedDate=formatDate(modified);//Addthislinefinalblocks=document.getBlocks();returnScaffold(appBar:AppBar(title:Text(title)),body:Column(children:[Text('Last modified: $formattedModifiedDate'),//ModifythislineExpanded(child:ListView.builder(itemCount:blocks.length,itemBuilder:(context,index){returnBlockWidget(block:blocks[index]);},),),],),);}}

2. Hot reload to see the changes in your app:

12. Seal a class for exhaustive switching

Notice that you didn't use a wildcard or default case at the end of the last switch. Though it's good practice to always include a case for values that might fall through, it's ok in a simple example like this since you know the cases you defined account forall of the possible valuesinDays could potentially take.

When every case in a switch is handled, it's called anexhaustive switch. For example, switching on abool type is exhaustive when it has cases fortrue andfalse. Switching on anenum type is exhaustive when there are cases for each of the enum's values, too, because enums represent afixed number ofconstant values.

Dart 3 extendedexhaustiveness checking to objects and class hierarchies with the new class modifiersealed. Refactor yourBlock class as a sealed superclass.

Create the subclasses

• Indata.dart, create three new classes—HeaderBlock,ParagraphBlock, andCheckboxBlock—that extendBlock:

lib/data.dart

classHeaderBlockextendsBlock{finalStringtext;HeaderBlock(this.text);}classParagraphBlockextendsBlock{finalStringtext;ParagraphBlock(this.text);}classCheckboxBlockextendsBlock{finalStringtext;finalboolisChecked;CheckboxBlock(this.text,this.isChecked);}

Each of these classes corresponds to the differenttype values from the original JSON:'h1','p', and'checkbox'.

Seal the superclass

• Mark theBlock class assealed. Then, refactor the if-case as a switch expression that returns the subclass corresponding to thetype specified in the JSON:

lib/data.dart

sealedclassBlock{Block();factoryBlock.fromJson(Map<String,Object?>json){returnswitch(json){{'type':'h1','text':Stringtext}=>HeaderBlock(text),{'type':'p','text':Stringtext}=>ParagraphBlock(text),{'type':'checkbox','text':Stringtext,'checked':boolchecked}=>CheckboxBlock(text,checked),_=>throwconstFormatException('Unexpected JSON format'),};}}

Thesealed keyword is aclass modifier that means you canonly extend or implement this class in the same library. Since the analyzer knows the subtypes of this class, it reports an error if a switch fails to cover one of them and isn't exhaustive.

Use a switch expression in order to display widgets

1. Update theBlockWidget class inmain.dart with a switch expression that uses object patterns for each case:

lib/main.dart

classBlockWidgetextendsStatelessWidget{finalBlockblock;constBlockWidget({requiredthis.block,super.key});@overrideWidgetbuild(BuildContextcontext){returnContainer(margin:constEdgeInsets.all(8),child:switch(block){HeaderBlock(:finaltext)=>Text(text,style:Theme.of(context).textTheme.displayMedium,),ParagraphBlock(:finaltext)=>Text(text),CheckboxBlock(:finaltext,:finalisChecked)=>Row(children:[Checkbox(value:isChecked,onChanged:(_){}),Text(text),],),},);}}

In your first version ofBlockWidget, you switched on a field of aBlock object to return aTextStyle. Now, you switch an instance of theBlock object itself and match againstobject patterns that represent its subclasses, extracting the object's properties in the process.

The Dart analyzer can check that each subclass is handled in the switch expression because you madeBlock a sealed class.