iOS/Pods/GoogleUtilities/GoogleUtilities/UserDefaults/Private/GULUserDefaults.h

   1 // Copyright 2018 Google
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //      http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 #import <Foundation/Foundation.h>
  16
  17 NS_ASSUME_NONNULL_BEGIN
  18
  19 /// A thread-safe user defaults that uses C functions from CFPreferences.h instead of
  20 /// `NSUserDefaults`. This is to avoid sending an `NSNotification` when it's changed from a
  21 /// background thread to avoid crashing. // TODO: Insert radar number here.
  22 @interface GULUserDefaults : NSObject
  23
  24 /// A shared user defaults similar to +[NSUserDefaults standardUserDefaults] and accesses the same
  25 /// data of the standardUserDefaults.
  26 + (GULUserDefaults *)standardUserDefaults;
  27
  28 /// Initializes preferences with a suite name that is the same with the NSUserDefaults' suite name.
  29 /// Both of CFPreferences and NSUserDefaults share the same plist file so their data will exactly
  30 /// the same.
  31 ///
  32 /// @param suiteName The name of the suite of the user defaults.
  33 - (instancetype)initWithSuiteName:(nullable NSString *)suiteName;
  34
  35 #pragma mark - Getters
  36
  37 /// Searches the receiver's search list for a default with the key 'defaultName' and return it. If
  38 /// another process has changed defaults in the search list, NSUserDefaults will automatically
  39 /// update to the latest values. If the key in question has been marked as ubiquitous via a Defaults
  40 /// Configuration File, the latest value may not be immediately available, and the registered value
  41 /// will be returned instead.
  42 - (nullable id)objectForKey:(NSString *)defaultName;
  43
  44 /// Equivalent to -objectForKey:, except that it will return nil if the value is not an NSArray.
  45 - (nullable NSArray *)arrayForKey:(NSString *)defaultName;
  46
  47 /// Equivalent to -objectForKey:, except that it will return nil if the value
  48 /// is not an NSDictionary.
  49 - (nullable NSDictionary<NSString *, id> *)dictionaryForKey:(NSString *)defaultName;
  50
  51 /// Equivalent to -objectForKey:, except that it will convert NSNumber values to their NSString
  52 /// representation. If a non-string non-number value is found, nil will be returned.
  53 - (nullable NSString *)stringForKey:(NSString *)defaultName;
  54
  55 /// Equivalent to -objectForKey:, except that it converts the returned value to an NSInteger. If the
  56 /// value is an NSNumber, the result of -integerValue will be returned. If the value is an NSString,
  57 /// it will be converted to NSInteger if possible. If the value is a boolean, it will be converted
  58 /// to either 1 for YES or 0 for NO. If the value is absent or can't be converted to an integer, 0
  59 /// will be returned.
  60 - (NSInteger)integerForKey:(NSString *)defaultName;
  61
  62 /// Similar to -integerForKey:, except that it returns a float, and boolean values will not be
  63 /// converted.
  64 - (float)floatForKey:(NSString *)defaultName;
  65
  66 /// Similar to -integerForKey:, except that it returns a double, and boolean values will not be
  67 /// converted.
  68 - (double)doubleForKey:(NSString *)defaultName;
  69
  70 /// Equivalent to -objectForKey:, except that it converts the returned value to a BOOL. If the value
  71 /// is an NSNumber, NO will be returned if the value is 0, YES otherwise. If the value is an
  72 /// NSString, values of "YES" or "1" will return YES, and values of "NO", "0", or any other string
  73 /// will return NO. If the value is absent or can't be converted to a BOOL, NO will be returned.
  74 - (BOOL)boolForKey:(NSString *)defaultName;
  75
  76 #pragma mark - Setters
  77
  78 /// Immediately stores a value (or removes the value if `nil` is passed as the value) for the
  79 /// provided key in the search list entry for the receiver's suite name in the current user and any
  80 /// host, then asynchronously stores the value persistently, where it is made available to other
  81 /// processes.
  82 - (void)setObject:(nullable id)value forKey:(NSString *)defaultName;
  83
  84 /// Equivalent to -setObject:forKey: except that the value is converted from a float to an NSNumber.
  85 - (void)setFloat:(float)value forKey:(NSString *)defaultName;
  86
  87 /// Equivalent to -setObject:forKey: except that the value is converted from a double to an
  88 /// NSNumber.
  89 - (void)setDouble:(double)value forKey:(NSString *)defaultName;
  90
  91 /// Equivalent to -setObject:forKey: except that the value is converted from an NSInteger to an
  92 /// NSNumber.
  93 - (void)setInteger:(NSInteger)value forKey:(NSString *)defaultName;
  94
  95 /// Equivalent to -setObject:forKey: except that the value is converted from a BOOL to an NSNumber.
  96 - (void)setBool:(BOOL)value forKey:(NSString *)defaultName;
  97
  98 #pragma mark - Removing Defaults
  99
 100 /// Equivalent to -[... setObject:nil forKey:defaultName]
 101 - (void)removeObjectForKey:(NSString *)defaultName;
 102
 103 #pragma mark - Save data
 104
 105 /// Blocks the calling thread until all in-progress set operations have completed.
 106 - (void)synchronize;
 107
 108 @end
 109
 110 NS_ASSUME_NONNULL_END