0
# Storage Operations
1

2
Core storage operations for all supported data types including primitives, strings, byte arrays, and Parcelable objects. MMKV provides both MMKV-native methods and SharedPreferences-compatible methods for seamless migration.
3

4
## Capabilities
5

6
### Boolean Operations
7

8
Store and retrieve boolean values with optional expiration support.
9

10
```java { .api }
11
/**
12
 * Store a boolean value.
13
 * @param key The key to store the value under
14
 * @param value The boolean value to store
15
 * @return true if successful, false otherwise
16
 */
17
public boolean encode(String key, boolean value);
18

19
/**
20
 * Store a boolean value with custom expiration.
21
 * @param key The key to store the value under
22
 * @param value The boolean value to store
23
 * @param expireDurationInSecond Override the default duration, ExpireNever (0) means never expire
24
 * @return true if successful, false otherwise
25
 */
26
public boolean encode(String key, boolean value, int expireDurationInSecond);
27

28
/**
29
 * Retrieve a boolean value.
30
 * @param key The key to retrieve the value for
31
 * @return The boolean value, or false if not found
32
 */
33
public boolean decodeBool(String key);
34

35
/**
36
 * Retrieve a boolean value with default.
37
 * @param key The key to retrieve the value for
38
 * @param defaultValue The default value to return if key is not found
39
 * @return The boolean value, or defaultValue if not found
40
 */
41
public boolean decodeBool(String key, boolean defaultValue);
42
```
43

44
**Usage Example:**
45

46
```java
47
MMKV kv = MMKV.defaultMMKV();
48

49
// Store boolean values
50
kv.encode("is_first_launch", true);
51
kv.encode("notifications_enabled", false);
52

53
// Store with expiration (1 hour)
54
kv.encode("temporary_flag", true, MMKV.ExpireInHour);
55

56
// Retrieve boolean values
57
boolean isFirst = kv.decodeBool("is_first_launch"); // false if not found
58
boolean notificationsEnabled = kv.decodeBool("notifications_enabled", true); // true if not found
59
```
60

61
### Integer Operations
62

63
Store and retrieve integer values with optional expiration support.
64

65
```java { .api }
66
/**
67
 * Store an integer value.
68
 * @param key The key to store the value under
69
 * @param value The integer value to store
70
 * @return true if successful, false otherwise
71
 */
72
public boolean encode(String key, int value);
73

74
/**
75
 * Store an integer value with custom expiration.
76
 * @param key The key to store the value under
77
 * @param value The integer value to store
78
 * @param expireDurationInSecond Override the default duration, ExpireNever (0) means never expire
79
 * @return true if successful, false otherwise
80
 */
81
public boolean encode(String key, int value, int expireDurationInSecond);
82

83
/**
84
 * Retrieve an integer value.
85
 * @param key The key to retrieve the value for
86
 * @return The integer value, or 0 if not found
87
 */
88
public int decodeInt(String key);
89

90
/**
91
 * Retrieve an integer value with default.
92
 * @param key The key to retrieve the value for
93
 * @param defaultValue The default value to return if key is not found
94
 * @return The integer value, or defaultValue if not found
95
 */
96
public int decodeInt(String key, int defaultValue);
97
```
98

99
**Usage Example:**
100

101
```java
102
// Store integer values
103
kv.encode("user_id", 12345);
104
kv.encode("retry_count", 3);
105

106
// Store with expiration (24 hours)
107
kv.encode("daily_login_bonus", 100, MMKV.ExpireInDay);
108

109
// Retrieve integer values
110
int userId = kv.decodeInt("user_id", -1);
111
int retryCount = kv.decodeInt("retry_count", 0);
112
```
113

114
### Long Operations
115

116
Store and retrieve long values for large numbers and timestamps.
117

118
```java { .api }
119
/**
120
 * Store a long value.
121
 * @param key The key to store the value under
122
 * @param value The long value to store
123
 * @return true if successful, false otherwise
124
 */
125
public boolean encode(String key, long value);
126

127
/**
128
 * Store a long value with custom expiration.
129
 * @param key The key to store the value under
130
 * @param value The long value to store
131
 * @param expireDurationInSecond Override the default duration, ExpireNever (0) means never expire
132
 * @return true if successful, false otherwise
133
 */
134
public boolean encode(String key, long value, int expireDurationInSecond);
135

136
/**
137
 * Retrieve a long value.
138
 * @param key The key to retrieve the value for
139
 * @return The long value, or 0 if not found
140
 */
141
public long decodeLong(String key);
142

143
/**
144
 * Retrieve a long value with default.
145
 * @param key The key to retrieve the value for
146
 * @param defaultValue The default value to return if key is not found
147
 * @return The long value, or defaultValue if not found
148
 */
149
public long decodeLong(String key, long defaultValue);
150
```
151

152
**Usage Example:**
153

154
```java
155
// Store timestamps and large numbers
156
kv.encode("last_sync_time", System.currentTimeMillis());
157
kv.encode("total_score", 9876543210L);
158

159
// Store with expiration
160
kv.encode("session_start", System.currentTimeMillis(), MMKV.ExpireInHour);
161

162
// Retrieve long values
163
long lastSync = kv.decodeLong("last_sync_time", 0);
164
long totalScore = kv.decodeLong("total_score", 0L);
165
```
166

167
### Float Operations
168

169
Store and retrieve float values for decimal numbers.
170

171
```java { .api }
172
/**
173
 * Store a float value.
174
 * @param key The key to store the value under
175
 * @param value The float value to store
176
 * @return true if successful, false otherwise
177
 */
178
public boolean encode(String key, float value);
179

180
/**
181
 * Store a float value with custom expiration.
182
 * @param key The key to store the value under
183
 * @param value The float value to store
184
 * @param expireDurationInSecond Override the default duration, ExpireNever (0) means never expire
185
 * @return true if successful, false otherwise
186
 */
187
public boolean encode(String key, float value, int expireDurationInSecond);
188

189
/**
190
 * Retrieve a float value.
191
 * @param key The key to retrieve the value for
192
 * @return The float value, or 0.0f if not found
193
 */
194
public float decodeFloat(String key);
195

196
/**
197
 * Retrieve a float value with default.
198
 * @param key The key to retrieve the value for
199
 * @param defaultValue The default value to return if key is not found
200
 * @return The float value, or defaultValue if not found
201
 */
202
public float decodeFloat(String key, float defaultValue);
203
```
204

205
**Usage Example:**
206

207
```java
208
// Store float values
209
kv.encode("user_rating", 4.5f);
210
kv.encode("progress_percentage", 0.75f);
211

212
// Retrieve float values
213
float rating = kv.decodeFloat("user_rating", 0.0f);
214
float progress = kv.decodeFloat("progress_percentage", 0.0f);
215
```
216

217
### Double Operations
218

219
Store and retrieve double values for high-precision decimal numbers.
220

221
```java { .api }
222
/**
223
 * Store a double value.
224
 * @param key The key to store the value under
225
 * @param value The double value to store
226
 * @return true if successful, false otherwise
227
 */
228
public boolean encode(String key, double value);
229

230
/**
231
 * Store a double value with custom expiration.
232
 * @param key The key to store the value under
233
 * @param value The double value to store
234
 * @param expireDurationInSecond Override the default duration, ExpireNever (0) means never expire
235
 * @return true if successful, false otherwise
236
 */
237
public boolean encode(String key, double value, int expireDurationInSecond);
238

239
/**
240
 * Retrieve a double value.
241
 * @param key The key to retrieve the value for
242
 * @return The double value, or 0.0 if not found
243
 */
244
public double decodeDouble(String key);
245

246
/**
247
 * Retrieve a double value with default.
248
 * @param key The key to retrieve the value for
249
 * @param defaultValue The default value to return if key is not found
250
 * @return The double value, or defaultValue if not found
251
 */
252
public double decodeDouble(String key, double defaultValue);
253
```
254

255
**Usage Example:**
256

257
```java
258
// Store high-precision values
259
kv.encode("latitude", 37.7749295);
260
kv.encode("longitude", -122.4194155);
261
kv.encode("account_balance", 1234.56789);
262

263
// Retrieve double values
264
double lat = kv.decodeDouble("latitude", 0.0);
265
double lon = kv.decodeDouble("longitude", 0.0);
266
```
267

268
### String Operations
269

270
Store and retrieve string values with full Unicode support.
271

272
```java { .api }
273
/**
274
 * Store a string value.
275
 * @param key The key to store the value under
276
 * @param value The string value to store (nullable)
277
 * @return true if successful, false otherwise
278
 */
279
public boolean encode(String key, String value);
280

281
/**
282
 * Store a string value with custom expiration.
283
 * @param key The key to store the value under
284
 * @param value The string value to store (nullable)
285
 * @param expireDurationInSecond Override the default duration, ExpireNever (0) means never expire
286
 * @return true if successful, false otherwise
287
 */
288
public boolean encode(String key, String value, int expireDurationInSecond);
289

290
/**
291
 * Retrieve a string value.
292
 * @param key The key to retrieve the value for
293
 * @return The string value, or null if not found
294
 */
295
public String decodeString(String key);
296

297
/**
298
 * Retrieve a string value with default.
299
 * @param key The key to retrieve the value for
300
 * @param defaultValue The default value to return if key is not found (nullable)
301
 * @return The string value, or defaultValue if not found
302
 */
303
public String decodeString(String key, String defaultValue);
304
```
305

306
**Usage Example:**
307

308
```java
309
// Store string values
310
kv.encode("username", "alice_smith");
311
kv.encode("user_email", "alice@example.com");
312
kv.encode("welcome_message", "Welcome to our app! 🎉");
313

314
// Store with expiration
315
kv.encode("session_token", "abc123xyz", MMKV.ExpireInHour);
316

317
// Store null value (removes key)
318
kv.encode("temp_data", null);
319

320
// Retrieve string values
321
String username = kv.decodeString("username", "guest");
322
String email = kv.decodeString("user_email"); // null if not found
323
```
324

325
### String Set Operations
326

327
Store and retrieve sets of strings for collections of unique string values.
328

329
```java { .api }
330
/**
331
 * Store a string set value.
332
 * @param key The key to store the value under
333
 * @param value The string set to store (nullable)
334
 * @return true if successful, false otherwise
335
 */
336
public boolean encode(String key, Set<String> value);
337

338
/**
339
 * Store a string set value with custom expiration.
340
 * @param key The key to store the value under
341
 * @param value The string set to store (nullable)
342
 * @param expireDurationInSecond Override the default duration, ExpireNever (0) means never expire
343
 * @return true if successful, false otherwise
344
 */
345
public boolean encode(String key, Set<String> value, int expireDurationInSecond);
346

347
/**
348
 * Retrieve a string set value.
349
 * @param key The key to retrieve the value for
350
 * @return The string set, or null if not found
351
 */
352
public Set<String> decodeStringSet(String key);
353

354
/**
355
 * Retrieve a string set value with default.
356
 * @param key The key to retrieve the value for
357
 * @param defaultValue The default value to return if key is not found (nullable)
358
 * @return The string set, or defaultValue if not found
359
 */
360
public Set<String> decodeStringSet(String key, Set<String> defaultValue);
361

362
/**
363
 * Retrieve a string set value with default and custom Set implementation.
364
 * @param key The key to retrieve the value for
365
 * @param defaultValue The default value to return if key is not found (nullable)
366
 * @param cls The Set implementation class to use (e.g., HashSet.class, LinkedHashSet.class)
367
 * @return The string set, or defaultValue if not found
368
 */
369
public Set<String> decodeStringSet(String key, Set<String> defaultValue, Class<? extends Set> cls);
370
```
371

372
**Usage Example:**
373

374
```java
375
// Store string sets
376
Set<String> permissions = new HashSet<>();
377
permissions.add("camera");
378
permissions.add("location");
379
permissions.add("storage");
380
kv.encode("granted_permissions", permissions);
381

382
Set<String> favoriteColors = new LinkedHashSet<>();
383
favoriteColors.add("blue");
384
favoriteColors.add("green");
385
favoriteColors.add("red");
386
kv.encode("favorite_colors", favoriteColors, MMKV.ExpireInDay);
387

388
// Retrieve string sets
389
Set<String> grantedPerms = kv.decodeStringSet("granted_permissions", new HashSet<>());
390
Set<String> colors = kv.decodeStringSet("favorite_colors", null, LinkedHashSet.class);
391
```
392

393
### Byte Array Operations
394

395
Store and retrieve raw byte data for binary content, images, or serialized objects.
396

397
```java { .api }
398
/**
399
 * Store a byte array value.
400
 * @param key The key to store the value under
401
 * @param value The byte array to store (nullable)
402
 * @return true if successful, false otherwise
403
 */
404
public boolean encode(String key, byte[] value);
405

406
/**
407
 * Store a byte array value with custom expiration.
408
 * @param key The key to store the value under
409
 * @param value The byte array to store (nullable)
410
 * @param expireDurationInSecond Override the default duration, ExpireNever (0) means never expire
411
 * @return true if successful, false otherwise
412
 */
413
public boolean encode(String key, byte[] value, int expireDurationInSecond);
414

415
/**
416
 * Retrieve a byte array value.
417
 * @param key The key to retrieve the value for
418
 * @return The byte array, or null if not found
419
 */
420
public byte[] decodeBytes(String key);
421

422
/**
423
 * Retrieve a byte array value with default.
424
 * @param key The key to retrieve the value for
425
 * @param defaultValue The default value to return if key is not found (nullable)
426
 * @return The byte array, or defaultValue if not found
427
 */
428
public byte[] decodeBytes(String key, byte[] defaultValue);
429
```
430

431
**Usage Example:**
432

433
```java
434
// Store binary data
435
String jsonData = "{\"user\":\"alice\",\"id\":123}";
436
kv.encode("cached_response", jsonData.getBytes(StandardCharsets.UTF_8));
437

438
// Store image data
439
Bitmap bitmap = getBitmapFromResource();
440
ByteArrayOutputStream stream = new ByteArrayOutputStream();
441
bitmap.compress(Bitmap.CompressFormat.PNG, 100, stream);
442
kv.encode("cached_avatar", stream.toByteArray(), MMKV.ExpireInDay);
443

444
// Retrieve binary data
445
byte[] cachedResponse = kv.decodeBytes("cached_response");
446
if (cachedResponse != null) {
447
    String json = new String(cachedResponse, StandardCharsets.UTF_8);
448
}
449

450
byte[] avatarData = kv.decodeBytes("cached_avatar", new byte[0]);
451
```
452

453
### Parcelable Operations
454

455
Store and retrieve Android Parcelable objects for complex data structures.
456

457
```java { .api }
458
/**
459
 * Store a Parcelable object.
460
 * @param key The key to store the value under
461
 * @param value The Parcelable object to store (nullable)
462
 * @return true if successful, false otherwise
463
 */
464
public boolean encode(String key, Parcelable value);
465

466
/**
467
 * Store a Parcelable object with custom expiration.
468
 * @param key The key to store the value under
469
 * @param value The Parcelable object to store (nullable)
470
 * @param expireDurationInSecond Override the default duration, ExpireNever (0) means never expire
471
 * @return true if successful, false otherwise
472
 */
473
public boolean encode(String key, Parcelable value, int expireDurationInSecond);
474

475
/**
476
 * Retrieve a Parcelable object.
477
 * @param key The key to retrieve the value for
478
 * @param tClass The class of the Parcelable object
479
 * @return The Parcelable object, or null if not found
480
 */
481
public <T extends Parcelable> T decodeParcelable(String key, Class<T> tClass);
482

483
/**
484
 * Retrieve a Parcelable object with default.
485
 * @param key The key to retrieve the value for
486
 * @param tClass The class of the Parcelable object
487
 * @param defaultValue The default value to return if key is not found (nullable)
488
 * @return The Parcelable object, or defaultValue if not found
489
 */
490
public <T extends Parcelable> T decodeParcelable(String key, Class<T> tClass, T defaultValue);
491
```
492

493
**Usage Example:**
494

495
```java
496
// Store custom Parcelable objects
497
User user = new User("Alice", "alice@example.com", 25);
498
kv.encode("current_user", user);
499

500
Location location = new Location("GPS");
501
location.setLatitude(37.7749);
502
location.setLongitude(-122.4194);
503
kv.encode("last_location", location, MMKV.ExpireInHour);
504

505
// Retrieve Parcelable objects
506
User currentUser = kv.decodeParcelable("current_user", User.class);
507
Location lastLocation = kv.decodeParcelable("last_location", Location.class, null);
508
```
509

510
### SharedPreferences Compatibility
511

512
MMKV provides drop-in replacement methods for SharedPreferences interface.
513

514
```java { .api }
515
// SharedPreferences interface methods
516
public String getString(String key, String defValue);
517
public Set<String> getStringSet(String key, Set<String> defValues);
518
public int getInt(String key, int defValue);
519
public long getLong(String key, long defValue);
520
public float getFloat(String key, float defValue);
521
public boolean getBoolean(String key, boolean defValue);
522
public boolean contains(String key);
523

524
// SharedPreferences.Editor interface methods
525
public Editor putString(String key, String value);
526
public Editor putString(String key, String value, int expireDurationInSecond);
527
public Editor putStringSet(String key, Set<String> values);
528
public Editor putStringSet(String key, Set<String> values, int expireDurationInSecond);
529
public Editor putInt(String key, int value);
530
public Editor putInt(String key, int value, int expireDurationInSecond);
531
public Editor putLong(String key, long value);
532
public Editor putLong(String key, long value, int expireDurationInSecond);
533
public Editor putFloat(String key, float value);
534
public Editor putFloat(String key, float value, int expireDurationInSecond);
535
public Editor putBoolean(String key, boolean value);
536
public Editor putBoolean(String key, boolean value, int expireDurationInSecond);
537
public Editor putBytes(String key, byte[] bytes);
538
public Editor putBytes(String key, byte[] bytes, int expireDurationInSecond);
539
public byte[] getBytes(String key, byte[] defValue);
540
public Editor remove(String key);
541
public Editor clear();
542
public Editor edit();
543
```
544

545
**Usage Example:**
546

547
```java
548
// Use MMKV as SharedPreferences drop-in replacement
549
SharedPreferences prefs = MMKV.defaultMMKV();
550

551
// Read values using SharedPreferences interface
552
String username = prefs.getString("username", "guest");
553
int userId = prefs.getInt("user_id", -1);
554
boolean isLoggedIn = prefs.getBoolean("is_logged_in", false);
555

556
// Write values using Editor interface
557
SharedPreferences.Editor editor = prefs.edit();
558
editor.putString("username", "alice")
559
      .putInt("user_id", 12345)
560
      .putBoolean("is_logged_in", true)
561
      .apply(); // or commit()
562

563
// MMKV-specific extensions with expiration
564
MMKV mmkv = (MMKV) prefs;
565
mmkv.putString("session_token", "abc123", MMKV.ExpireInHour);
566
mmkv.putBytes("cached_data", responseData, MMKV.ExpireInDay);
567
```
568

569
## Constants
570

571
```java { .api }
572
// Expiration constants (in seconds)
573
public static final int ExpireNever = 0;                    // Never expire
574
public static final int ExpireInMinute = 60;                // 1 minute
575
public static final int ExpireInHour = 60 * 60;             // 1 hour
576
public static final int ExpireInDay = 24 * 60 * 60;         // 1 day
577
public static final int ExpireInMonth = 30 * 24 * 60 * 60;  // 30 days
578
public static final int ExpireInYear = 365 * 30 * 24 * 60 * 60; // 365 days
579
```