[shared_preferences] Documentation update for Readme.md (#4684)
diff --git a/packages/shared_preferences/shared_preferences/CHANGELOG.md b/packages/shared_preferences/shared_preferences/CHANGELOG.md
index 978fab9..36e60cc 100644
--- a/packages/shared_preferences/shared_preferences/CHANGELOG.md
+++ b/packages/shared_preferences/shared_preferences/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 2.0.13
+
+* Updates documentation on README.md.
+
## 2.0.12
* Removes dependency on `meta`.
diff --git a/packages/shared_preferences/shared_preferences/README.md b/packages/shared_preferences/shared_preferences/README.md
index 46d022f..d3295ac 100644
--- a/packages/shared_preferences/shared_preferences/README.md
+++ b/packages/shared_preferences/shared_preferences/README.md
@@ -3,38 +3,54 @@
[](https://pub.dev/packages/shared_preferences)
Wraps platform-specific persistent storage for simple data
-(NSUserDefaults on iOS and macOS, SharedPreferences on Android, etc.). Data may be persisted to disk asynchronously,
+(NSUserDefaults on iOS and macOS, SharedPreferences on Android, etc.).
+Data may be persisted to disk asynchronously,
and there is no guarantee that writes will be persisted to disk after
returning, so this plugin must not be used for storing critical data.
+Supported data types are `int`, `double`, `bool`, `String` and `List<String>`.
+
## Usage
To use this plugin, add `shared_preferences` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/platform-integration/platform-channels).
-### Example
+### Examples
+Here are small examples that show you how to use the API.
-``` dart
-import 'package:flutter/material.dart';
-import 'package:shared_preferences/shared_preferences.dart';
+#### Write data
+```dart
+// Obtain shared preferences.
+final prefs = await SharedPreferences.getInstance();
-void main() {
- runApp(MaterialApp(
- home: Scaffold(
- body: Center(
- child: RaisedButton(
- onPressed: _incrementCounter,
- child: Text('Increment Counter'),
- ),
- ),
- ),
- ));
-}
+// Save an integer value to 'counter' key.
+await prefs.setInt('counter', 10);
+// Save an boolean value to 'repeat' key.
+await prefs.setBool('repeat', true);
+// Save an double value to 'decimal' key.
+await prefs.setDouble('decimal', 1.5);
+// Save an String value to 'action' key.
+await prefs.setString('action', 'Start');
+// Save an list of strings to 'items' key.
+await prefs.setStringList('items', <String>['Earth', 'Moon', 'Sun']);
+```
-_incrementCounter() async {
- SharedPreferences prefs = await SharedPreferences.getInstance();
- int counter = (prefs.getInt('counter') ?? 0) + 1;
- print('Pressed $counter times.');
- await prefs.setInt('counter', counter);
-}
+#### Read data
+```dart
+// Try reading data from the 'counter' key. If it doesn't exist, returns null.
+final int? counter = prefs.getInt('counter');
+// Try reading data from the 'repeat' key. If it doesn't exist, returns null.
+final bool? repeat = prefs.getBool('repeat');
+// Try reading data from the 'decimal' key. If it doesn't exist, returns null.
+final double? decimal = prefs.getDouble('decimal');
+// Try reading data from the 'action' key. If it doesn't exist, returns null.
+final String? action = prefs.getString('action');
+// Try reading data from the 'items' key. If it doesn't exist, returns null.
+final List<String>? items = prefs.getStringList('items');
+```
+
+#### Remove an entry
+```dart
+// Remove data for the 'counter' key.
+final success = await prefs.remove('counter');
```
### Testing
@@ -45,3 +61,14 @@
Map<String, Object> values = <String, Object>{'counter': 1};
SharedPreferences.setMockInitialValues(values);
```
+
+### Storage location by platform
+
+| Platform | Location |
+| :--- | :--- |
+| Android | SharedPreferences |
+| iOS | NSUserDefaults |
+| Linux | In the XDG_DATA_HOME directory |
+| macOS | NSUserDefaults |
+| Web | LocalStorage |
+| Windows | In the roaming AppData directory |
diff --git a/packages/shared_preferences/shared_preferences/pubspec.yaml b/packages/shared_preferences/shared_preferences/pubspec.yaml
index d942b2b..39b48ef 100644
--- a/packages/shared_preferences/shared_preferences/pubspec.yaml
+++ b/packages/shared_preferences/shared_preferences/pubspec.yaml
@@ -3,7 +3,7 @@
Wraps NSUserDefaults on iOS and SharedPreferences on Android.
repository: https://github.com/flutter/plugins/tree/main/packages/shared_preferences/shared_preferences
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+shared_preferences%22
-version: 2.0.12
+version: 2.0.13
environment:
sdk: ">=2.14.0 <3.0.0"
