Getting a Key-value Pair

In order to get a key-value pair from a KiiObject, call the getForKey(_:) method of the KiiObject class. The getForKey(_:) method returns a value as an object of the id type. In Swift, a value can be obtained by downcasting a return value to an expected data type.

Specify the key for the value to get as the argument of the getForKey(_:) method. The value of the key at the first level of the JSON document hierarchy will be obtained.

The following is a sample JSON document and code to get values from the JSON document. The comments in the code show values to be obtained. For sample code that includes a step to get a KiiObject, see Getting a value of a basic data type below.

{
  "score": 987,
  "premiumUser": false,
  "mode": "easy"
}

Swift:

let score = (object.getForKey("score") as! NSNumber).intValue // score=987
let mode = object.getForKey("mode") as! String // mode="easy"
let premiumUser = (object.getForKey("premiumUser") as! NSNumber).boolValue // premiumUser=false

Objective-C:

long score = [[object getObjectForKey:@"score"] integerValue]; // score=987
NSString *mode = [object getObjectForKey:@"mode"]; // mode=@"easy"
BOOL premiumUser = [[object getObjectForKey:@"premiumUser"] boolValue]; // premiumUser=NO

In order to get a value of a key at the second or subsequent level, get a value of the uppermost parent key at the first level as a JSON object.

Supported data types

The table below lists the supported data types. The "Obtained value" column contains the values that are obtained by getting the key-value pairs in the "Key-value pair in the JSON format" column with the method calls in the "Method call" column.

Note that the sample code in this topic forcibly downcast a value with as! assuming each key has a value of an expected data type. Otherwise, the mobile app will crash. Consider using as? as needed.

Swift:

Data type	Key-value pair in the JSON format	Method call	Obtained value
NSString	`"data":"123"`	`object.getForKey("data") as! String`	"123"
NSNumber(Int)	`"data":123`	`(object.getForKey("data") as! NSNumber).intValue`	123
NSNumber(Int64)	`"data":123`	`(object.getForKey("data") as! NSNumber).int64Value`	123
NSNumber(Double)	`"data":123.456`	`(object.getForKey("data") as! NSNumber).doubleValue`	123.456
NSNumber(Bool)	`"data":true`	`(object.getForKey("data") as! NSNumber).boolValue`	true
KiiGeoPoint	`"data":{` `"_type": "point",` `"lat": 35.658603,` `"lon": 139.745433` `}`	`object.getGeoPoint(forKey: "data")`	GeoPoint (35.658603, 139.745433)
NSArray	`"data":[1,2,3]`	`object.getForKey("data") as! NSArray`	[1,2,3]
NSDictionary	`"data":{"a":"b"}`	`object.getForKey("data") as! NSDictionary`	{"a":"b"}

Objective-C:

Data type	Key-value pair in the JSON format	Method call	Obtained value
NSString	`"data":"123"`	`[object getObjectForKey:@"data"];`	"123"
NSNumber(int)	`"data":123`	`[[object getObjectForKey:@"data"] integerValue];`	123
NSNumber(long long)	`"data":123`	`[[object getObjectForKey:@"data"] longLongValue];`	123
NSNumber(double)	`"data":123.456`	`[[object getObjectForKey:@"data"] doubleValue];`	123.456
NSNumber(BOOL)	`"data":true`	`[[object getObjectForKey:@"data"] boolValue];`	true
KiiGeoPoint	`"data":{` `"_type": "point",` `"lat": 35.658603,` `"lon": 139.745433` `}`	`[object getGeoPointForKey:@"data"];`	GeoPoint (35.658603, 139.745433)
NSArray	`"data":[1,2,3]`	`[object getObjectForKey:@"data"]`	[1,2,3]
NSDictionary	`"data":{"a":"b"}`	`[object getObjectForKey:@"data"]`	{"a":"b"}

Unlike the Android SDK, the iOS SDK does not provide a feature to convert a byte array to BASE64. If you need this feature, get the string and then perform the BASE64 decoding in your application.

Getting a value of a basic data type

To get key-value pairs from a KiiObject, use the getForKey(_:) method. To learn more, see the appledoc.

The following sample code illustrates how to get key-value pairs.

Swift:

// Instantiate a KiiObject.
let object = KiiObject(uri: uri)!

do {
  // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
  try object.refreshSynchronous()

  // Get key-value pairs.
  let stringData = object!.getForKey("stringValue") as! String
  let intData = (object!.getForKey("intValue") as! NSNumber).intValue
  let longData = (object!.getForKey("longValue") as! NSNumber).int64Value
  let doubleData = (object!.getForKey("doubleValue") as! NSNumber).doubleValue
  let booleanData = (object!.getForKey("booleanValue") as! NSNumber).boolValue
} catch let error as NSError {
  // Handle the error.
  return
}

// Instantiate a KiiObject.
let object = KiiObject(uri: uri)!

// Refresh the KiiObject to retrieve the latest data from Kii Cloud.
object.refresh { (object : KiiObject?, error : Error?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
  // Get key-value pairs.
  let stringData = object!.getForKey("stringValue") as! String
  let intData = (object!.getForKey("intValue") as! NSNumber).intValue
  let longData = (object!.getForKey("longValue") as! NSNumber).int64Value
  let doubleData = (object!.getForKey("doubleValue") as! NSNumber).doubleValue
  let booleanData = (object!.getForKey("booleanValue") as! NSNumber).boolValue
}

Objective-C:

NSError *error = nil;

// Instantiate a KiiObject.
KiiObject *object = [KiiObject objectWithURI:uri];

// Refresh the KiiObject to retrieve the latest data from Kii Cloud.
[object refreshSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Get key-value pairs.
NSString *stringData = [object getObjectForKey:@"stringValue"];
long intData = [[object getObjectForKey:@"intValue"] integerValue];
long long longData = [[object getObjectForKey:@"longValue"] longLongValue];
double doubleData = [[object getObjectForKey:@"doubleValue"] doubleValue];
BOOL booleanData = [[object getObjectForKey:@"booleanValue"] boolValue];

NSError *error = nil;

// Instantiate a KiiObject.
KiiObject *object = [KiiObject objectWithURI:uri];

// Refresh the KiiObject to retrieve the latest data from Kii Cloud.
[object refreshWithBlock:^(KiiObject *object, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }

  // Get key-value pairs.
  NSString *stringData = [object getObjectForKey:@"stringValue"];
  long intData = [[object getObjectForKey:@"intValue"] integerValue];
  long long longData = [[object getObjectForKey:@"longValue"] longLongValue];
  double doubleData = [[object getObjectForKey:@"doubleValue"] doubleValue];
  BOOL booleanData = [[object getObjectForKey:@"booleanValue"] boolValue];
}];

Make sure to call the refresh(_:) method after instantiating a KiiObject, or your local KiiObject will not be updated with the latest key-value pairs.

Getting a list of keys

To get a list of all key-value pairs set on a KiiObject, use the dictionaryValue() method to get and convert the list to an NSDictionary as shown in the following example:

Swift:

// Instantiate a KiiObject.
let object = bucket.createObject(withID: "_ID_OF_THE_OBJECT_")

do{
  // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
  try object.refreshSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

// Convert key-value pairs to Dictionary.
let dictionary = object.dictionaryValue()
for (key,value) in dictionary {
  // Do something with each key.
}

// Instantiate a KiiObject.
let object = bucket.createObject(withID: "_ID_OF_THE_OBJECT_")

// Refresh the KiiObject to retrieve the latest data from Kii Cloud.
object.refresh { (object : KiiObject?, error : Error?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  // Convert key-value pairs to Dictionary.
  let dictionary = object!.dictionaryValue()
  for (key,value) in dictionary {
    // Do something with each key.
  }
}

Objective-C:

NSError *error = nil;
KiiObject *object = nil;

@try {
  // Instantiate a KiiObject.
  object = [bucket createObjectWithID:@"_ID_OF_THE_OBJECT_"];
}
@catch (NSException *exp) {
  // The KiiObject ID is invalid.
  return;
}

// Refresh the KiiObject to retrieve the latest data from Kii Cloud.
[object refreshSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Convert key-value pairs to NSDictionary.
NSDictionary* dictionary = [object dictionaryValue];
for (NSString* key in [dictionary keyEnumerator]) {
  // Do something with each key.
}

KiiObject *object = nil;

@try {
  // Instantiate a KiiObject.
  object = [bucket createObjectWithID:@"_ID_OF_THE_OBJECT_"];
}
@catch (NSException *exp) {
  // The KiiObject ID is invalid.
  return;
}

// Refresh the KiiObject to retrieve the latest data from Kii Cloud.
[object refreshWithBlock:^(KiiObject *object, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }

  // Convert key-value pairs to NSDictionary.
  NSDictionary* dictionary = [object dictionaryValue];
  for (NSString* key in [dictionary keyEnumerator]) {
    // Do something with each key.
  }
}];

The dictionaryValue() method converts key-value pairs of both custom and predefined keys into an NSDictionary. For more information about the predefined keys, see Predefined Keys.

Getting an empty field

You will get a different value when a specified key does not exist and when a specified key has a null value.

Suppose that you are trying to get key-value pairs from the JSON document below.

{
  "key1": null,
  "key2": ""
}

Here are the results you will get:

Executing [json getObjectForKey:@"key1"] will return a NSNull.
Executing [json getObjectForKey:@"key2"] will return a NSString that represents an empty string.
Executing [json getObjectForKey:@"key3"] will return a nil.

For the details on the data type conversion, see Data Conversion in the SDK.

Getting the created and modified time

Kii Cloud automatically sets the created and modified time of a KiiObject. You can get them from the KiiObject's created and modified properties, respectively.

The times are in UNIX time (msec, UTC).

Getting a geolocation

To get a geolocation from a KiiObject, call the getGeoPoint(forKey_:) method to get a KiiGeoPoint object. Then, get the latitude and longitude from the latitude and longitude properties, respectively.

Swift:

// Get GeoPoints from the "location1" and "location2" keys.
let gp1 = object!.getGeoPoint(forKey: "location1")!
let gp2 = object!.getGeoPoint(forKey: "location2")!

// Get the latitude and longitude data.
let latitude1 = gp1.latitude
let longitude1 = gp1.longitude
let latitude2 = gp2.latitude
let longitude2 = gp2.longitude

Objective-C:

// Get GeoPoints from the "location1" and "location2" keys.
KiiGeoPoint *gp1 = [object getGeoPointForKey:@"location1"];
KiiGeoPoint *gp2 = [object getGeoPointForKey:@"location2"];

// Get the latitude and longitude data.
double latitude1 = [gp1 latitude];
double longitude1 = [gp1 longitude];
double latitude2 = [gp2 latitude];
double longitude2 = [gp2 longitude];

Getting complex data

To get a JSON object and an array of JSON objects from a KiiObject, cast them to the corresponding data type.

Here is the sample code for getting the data that are set by the sample code presented in Setting complex data.

Swift:

// Get a value of a JSON object.
let jsonObject = object!.getForKey("myJsonObject") as! NSDictionary

// Get a value of a JSON array.
let jsonArray = object!.getForKey("myJsonArray") as! NSArray
let jsonObject1 = jsonArray.object(at: 0)
let jsonObject2 = jsonArray.object(at: 1)

Objective-C:

// Get a value of a JSON object.
NSDictionary* jsonObject = [object getObjectForKey:@"myJsonObject"];

// Get a value of a JSON array.
NSArray* jsonArray = [object getObjectForKey:@"myJsonArray"];
NSDictionary* jsonObject1 = [jsonArray objectAtIndex:0];
NSDictionary* jsonObject2 = [jsonArray objectAtIndex:1];