SValue Class Reference
[Utility Classes and Functions]

#include <support/Value.h>

Detailed Description

A general-purpose data container, also known as a variant.

SValue is formally an abstract set of {key->value} mappings, where each key and value can be any typed blob of data. Standard data types are defined for strings, integers, IBinder objects, and other common data types. In addition, there are three special values: B_UNDEFINED_VALUE is a SValue that is not set; B_WILD_VALUE is a special value that can be thought of as being every possible value all at the same time; B_NULL_VALUE is used to indicate value that are being supplied but not specified (such as to use the default value for an optional parameter).

Note that the definition of SValue is very recursive -- it is a collection of key/value mappings, where both the key and value are themselves a SValue. As such, a SValue containing a single data item is conceptually actually the mapping {WILD->value}; because of the properties of WILD, a WILD key can appear more than one time so that a set of the values { A, B } can be constructed in a SValue as the mapping { {WILD->A}, {WILD->B} }. When iterating over and thinking of operations on a value, it is always viewed as a map in this way. However, there are many convenience functions for working with a value in its common form of a single {WILD->A} item.

Printing

Function for printing values in a nice format.

typedef status_t(* print_func )(const sptr< ITextOutput > &io, const SValue &val, uint32_t flags)

SValue pretty printer function.

status_t PrintToStream (const sptr< ITextOutput > &io, uint32_t flags=0) const

Print the value's contents in a pretty format.

static status_t RegisterPrintFunc (type_code type, print_func func)

Add a new printer function for a type code.

static status_t UnregisterPrintFunc (type_code type, print_func func=NULL)

Remove printer function for type code.

Archiving

Reading and writing as flat byte streams.

ssize_t Archive (const sptr< IByteOutput > &into) const

ssize_t Archive (SParcel &into) const

ssize_t ArchivedSize () const

ssize_t Unarchive (const sptr< IByteInput > &from)

ssize_t Unarchive (SParcel &from)

Type Conversions

Retrieve the value as a standard type, potentially performing a conversion.

sptr< SAtom > AsAtom (status_t *result=NULL) const

Convert value to a strong SAtom pointer.

sptr< IBinder > AsBinder (status_t *result=NULL) const

Convert value to a strong IBinder pointer.

bool AsBool (status_t *result=NULL) const

Convert value to boolean.

double AsDouble (status_t *result=NULL) const

Convert value to double.

float AsFloat (status_t *result=NULL) const

Convert value to float.

int32_t AsInt32 (status_t *result=NULL) const

Convert value to int32_t.

int64_t AsInt64 (status_t *result=NULL) const

Convert value to int64_t.

int32_t AsInteger (status_t *result=NULL) const

sptr< SKeyID > AsKeyID (status_t *result=NULL) const

Convert value to a wrapped PalmOS KeyID, SKeyID.

off_t AsOffset (status_t *result=NULL) const

Synonym for AsInt64().

ssize_t AsSSize (status_t *result=NULL) const

Convert value to a status/size code.

status_t AsStatus (status_t *result=NULL) const

Convert value to a status code.

SString AsString (status_t *result=NULL) const

Convert value to a SString.

nsecs_t AsTime (status_t *result=NULL) const

Convert value to nsecs_t.

wptr< SAtom > AsWeakAtom (status_t *result=NULL) const

Convert value to a weak SAtom pointer.

wptr< IBinder > AsWeakBinder (status_t *result=NULL) const

Convert value to a weak IBinder pointer.

Basic Operations

Assignment, status, existence, etc.

SValue & Assign (type_code type, const void *data, size_t len)

SValue & Assign (const SValue &o)

status_t ByteSwap (swap_action action)

status_t CanByteSwap () const

status_t ErrorCheck () const

Retrieve exception-level error.

bool IsDefined () const

Check whether the value is not B_UNDEFINED_VALUE.

bool IsObject () const

Check whether this value is an object, such as a binder.

bool IsSimple () const

Check whether this value is a single item of the form {WILD->A}.

bool IsSpecified () const

Check whether this value is neither B_UNDEFINED_VALUE nor B_WILD_VALUE.

bool IsWild () const

Checking whether this value is B_WILD_VALUE.

SValue & operator= (const SValue &o)

void SetError (status_t error)

Set an exception-level error code.

status_t StatusCheck () const

Return status of the value.

void Swap (SValue &with)

Exchange contents of 'this' and 'with'.

void Undefine ()

Set value to B_UNDEFINED_VALUE.

static void MoveAfter (SValue *to, SValue *from, size_t count=1)

Move value forward in memory (for implementation of BMoveAfter).

static void MoveBefore (SValue *to, SValue *from, size_t count=1)

Move value backward in memory (for implementation of BMoveBefore).

Raw Data Operations

Operations on the value as a raw blob of data with a type code. Note that these are not value for objects containing anything besides simple values. That is, values that are only the single mapping {WILD->data}.

void * BeginEditBytes (type_code type, size_t length, uint32_t flags=0)

Start raw editing of data in value.

const void * Data (type_code type, size_t *inoutMinLength) const

Retrieve data if value is type and length given.

const void * Data (type_code type, size_t length) const

Return the data if the value is the exact given type and length.

const void * Data () const

Return raw data in the value.

status_t EndEditBytes (ssize_t final_length=-1)

Finish raw editing after previously calling BeginEditBytes().

size_t Length () const

Return number of bytes of data in the value.

void Pool ()

Make sure value's data is in the SSharedBuffer pool.

status_t SetType (type_code newType)

Change this value's type code.

const SSharedBuffer * SharedBuffer () const

Return raw value data as a SSharedBuffer.

type_code Type () const

Return type code of data in this value.

Mapping Operations

Working with an SValue as structured data.

SValue * BeginEditItem (const SValue &key)

Direct editing of sub-items in the value.

int32_t CountItems () const

Count the number of mappings in the value.

void EndEditItem (SValue *item)

Finish sub-item editing after previously calling BeginEditItem().

void GetKeyIndices (const SValue *keys, size_t *outIndices, size_t count)

Given an array keys of values, returns their indices in this's value mapping.

status_t GetNextItem (void **cookie, SValue *out_key, SValue *out_value) const

Iterate over the mappings in the value.

bool HasItem (const SValue &key, const SValue &value=B_UNDEFINED_VALUE) const

Check whether this value contains the given mapping.

SValue & Inherit (const SValue &from, uint32_t flags=0)

Apply mappings underneath this value.

const SValue InheritCopy (const SValue &from, uint32_t flags=0) const

Non-destructive version of Inherit().

SValue & Join (const SValue &from, uint32_t flags=0)

Combine contents to two values together.

const SValue JoinCopy (const SValue &from, uint32_t flags=0) const

Non-destructive version of Join().

SValue & JoinItem (const SValue &key, const SValue &value, uint32_t flags=0)

Convenience function for overlaying a single map item.

SValue Keys () const

Get the keys from this value.

SValue & MapValues (const SValue &from, uint32_t flags=0)

Perform a value remapping operation.

const SValue MapValuesCopy (const SValue &from, uint32_t flags=0) const

Non-destructive version of MapValues().

const SValue operator * (const SValue &o) const

Synonym for MapValuesCopy().

SValue & operator *= (const SValue &o)

Synonym for MapValues().

const SValue operator+ (const SValue &o) const

Synonym for JoinCopy().

SValue & operator+= (const SValue &o)

Synonym for Join().

const SValue operator- (const SValue &o) const

Synonym for RemoveCopy().

SValue & operator-= (const SValue &o)

Synonym for Remove().

const SValue & operator[] (const static_large_string_value &key) const

Synonym for ValueFor().

const SValue & operator[] (const static_small_string_value &key) const

Synonym for ValueFor().

const SValue & operator[] (int32_t index) const

Synonym for ValueFor().

const SValue & operator[] (const SString &key) const

Synonym for ValueFor().

const SValue & operator[] (const char *key) const

Synonym for ValueFor().

const SValue & operator[] (const SValue &key) const

Synonym for ValueFor().

SValue & Overlay (const SValue &from, uint32_t flags=0)

Apply mappings on top of this value.

const SValue OverlayCopy (const SValue &from, uint32_t flags=0) const

Non-destructive version of Overlay().

SValue & Remove (const SValue &from, uint32_t flags=0)

Remove mappings from this value.

const SValue RemoveCopy (const SValue &from, uint32_t flags=0) const

Non-destructive version of Remove().

status_t RemoveItem (const SValue &key, const SValue &value=B_WILD_VALUE)

Convenience for Remove() of a single item/mapping.

status_t RenameItem (const SValue &old_key, const SValue &new_key)

Change the name of a key in the value.

const SValue & ReplaceValues (const SValue *values, const size_t *indices, size_t count)

Batch replace the values of a set of mappings.

SValue & Retain (const SValue &from, uint32_t flags=0)

Keep mappings in this value.

const SValue RetainCopy (const SValue &from, uint32_t flags=0) const

Non-destructive version of Retain().

const SValue & ValueFor (const static_large_string_value &str) const

Optimization of ValueFor() for static values.

const SValue & ValueFor (const static_small_string_value &str) const

Optimization of ValueFor() for static values.

const SValue & ValueFor (int32_t index) const

Optimization of ValueFor() for integers.

const SValue & ValueFor (const SString &str) const

Optimization of ValueFor() for SString.

const SValue & ValueFor (const char *str) const

Optimization of ValueFor() for raw character strings.

const SValue & ValueFor (const SValue &key) const

Optimization of ValueFor() with default flags.

const SValue ValueFor (const SValue &key, uint32_t flags) const

Look up a key in this value.

Comparison

The common SValue comparison operation is a quick binary compare of its type code and data. Not only is this fast, but the way values are compared is type-independent and thus will never change. The Compare() method and all comparison operators use this approach.

int32_t Compare (type_code type, const void *data, size_t length) const

int32_t Compare (const SString &str) const

int32_t Compare (const char *str) const

int32_t Compare (const SValue &o) const

int32_t LexicalCompare (const SValue &o) const

Perform a type-dependent comparison between two values.

bool operator!= (const static_large_string_value &str) const

bool operator!= (const static_small_string_value &str) const

bool operator!= (const SString &str) const

bool operator!= (const char *str) const

bool operator!= (const SValue &o) const

bool operator< (const static_large_string_value &str) const

bool operator< (const static_small_string_value &str) const

bool operator< (const SString &str) const

bool operator< (const char *str) const

bool operator< (const SValue &o) const

bool operator<= (const static_large_string_value &str) const

bool operator<= (const static_small_string_value &str) const

bool operator<= (const SString &str) const

bool operator<= (const char *str) const

bool operator<= (const SValue &o) const

bool operator== (const static_large_string_value &str) const

bool operator== (const static_small_string_value &str) const

bool operator== (const SString &str) const

bool operator== (const char *str) const

bool operator== (const SValue &o) const

bool operator> (const static_large_string_value &str) const

bool operator> (const static_small_string_value &str) const

bool operator> (const SString &str) const

bool operator> (const char *str) const

bool operator> (const SValue &o) const

bool operator>= (const static_large_string_value &str) const

bool operator>= (const static_small_string_value &str) const

bool operator>= (const SString &str) const

bool operator>= (const char *str) const

bool operator>= (const SValue &o) const

Typed Data Access

Retrieve data in value as a specific type, not performing conversion. (These functions fail if the value is not exactly the requested type.)

status_t GetAtom (sptr< SAtom > *atom) const

status_t GetBinder (sptr< IBinder > *obj) const

status_t GetBool (bool *val) const

status_t GetDouble (double *a_double) const

status_t GetFloat (float *a_float) const

status_t GetInt16 (int16_t *val) const

status_t GetInt32 (int32_t *val) const

status_t GetInt64 (int64_t *val) const

status_t GetInt8 (int8_t *val) const

status_t GetKeyID (sptr< SKeyID > *keyid) const

status_t GetStatus (status_t *val) const

status_t GetString (SString *a_string) const

status_t GetString (const char **a_string) const

status_t GetTime (nsecs_t *val) const

status_t GetWeakAtom (wptr< SAtom > *atom) const

status_t GetWeakBinder (wptr< IBinder > *obj) const

Constructors for Data

These constructors are used to create values containing a single piece of data of various types, which is implicitly the mapping {WILD->data}.

SValue (const sptr< SKeyID > &binder)

SValue (const wptr< IBinder > &binder)

SValue (const sptr< IBinder > &binder)

SValue (const static_large_string_value &str)

SValue (const static_small_string_value &str)

SValue (const SString &str)

SValue (const char *str)

SValue (int32_t num)

SValue (type_code type, const SSharedBuffer *buffer)

SValue (type_code type, const void *data, size_t len)

Constructors for Mappings

These constructors are used to create values containing a single explicit maping.

SValue (const SValue &key, const SValue &value, uint32_t flags, size_t numMappings)

SValue (const SValue &key, const SValue &value, uint32_t flags)

SValue (const SValue &key, const SValue &value)

Constructor and Destructor

SValue (const SValue &o)

SValue ()

~SValue ()

NOTE THAT THE DESTRUCTOR IS NOT VIRTUAL!

Creating Data Values

These static functions allow you to build SValues of various standard types. Note that it is bette to use SSimpleValue for int8_t, int16_t, int32_t, bool, and float types, and SSimpleStatusValue for status_t.

static SValue Atom (const sptr< SAtom > &value)

static SValue Binder (const sptr< IBinder > &value)

static SValue Bool (bool v)

static SValue Double (double value)

static SValue Float (float v)

static SValue Int16 (int16_t v)

static SValue Int32 (int32_t v)

static SValue Int64 (int64_t value)

static SValue Int8 (int8_t v)

static SValue KeyID (const sptr< SKeyID > &value)

static SValue Offset (off_t value)

static SValue SSize (ssize_t value)

static SValue Status (status_t error)

static SValue String (const SString &value)

static SValue String (const char *value)

static SValue Time (nsecs_t value)

static SValue WeakAtom (const wptr< SAtom > &value)

static SValue WeakBinder (const wptr< IBinder > &value)

Creating Special Values

Convenience functions to access special value types.

static const SValue & Null ()

The null value, synonym for B_NULL_VALUE.

static const SValue & Undefined ()

Not-a-value, synonym for B_UNDEFINED_VALUE.

static const SValue & Wild ()

The all-encompassing value, synonym for B_WILD_VALUE.

Static Public Member Functions

static const SValue & LookupConstantValue (int32_t index)

This is for internal use, do not use directly.

Friends

class BValueMap

Member Typedef Documentation

typedef status_t(* print_func)(const sptr< ITextOutput > &io, const SValue &val, uint32_t flags)

SValue pretty printer function.

Parameters:

io The stream to print in.

val The value to print.

flags Additional formatting information.

Constructor & Destructor Documentation

SValue ( ) [inline]

SValue ( const SValue & o ) [inline]

~SValue ( ) [inline]

NOTE THAT THE DESTRUCTOR IS NOT VIRTUAL!

SValue ( const SValue & key,

const SValue & value

) [inline]

SValue ( const SValue & key,

const SValue & value,

uint32_t flags

) [inline]

SValue ( const SValue & key,

const SValue & value,

uint32_t flags,

size_t numMappings

) [inline]

SValue ( type_code type,

const void * data,

size_t len

) [inline]

SValue ( type_code type,

const SSharedBuffer * buffer

)

SValue ( int32_t num ) [inline, explicit]

SValue ( const char * str ) [explicit]

SValue ( const SString & str ) [explicit]

SValue ( const static_small_string_value & str ) [inline, explicit]

SValue ( const static_large_string_value & str ) [inline, explicit]

SValue ( const sptr< IBinder > & binder )

SValue ( const wptr< IBinder > & binder )

SValue ( const sptr< SKeyID > & binder )

Member Function Documentation

ssize_t Archive ( const sptr< IByteOutput > & into ) const

ssize_t Archive ( SParcel & into ) const

ssize_t ArchivedSize ( ) const

sptr< SAtom > AsAtom ( status_t * result = NULL ) const

Convert value to a strong SAtom pointer.
Converts from the following types:

B_ATOM_TYPE: Returned as-is.
B_ATOM_WEAK_TYPE: Attempts to promote to strong pointer.
B_NULL_TYPE: Returns NULL. For all other types, returns NULL and 'result' is set to the current error/status code or B_BAD_TYPE.

sptr< IBinder > AsBinder ( status_t * result = NULL ) const

Convert value to a strong IBinder pointer.
Converts from the following types:

B_BINDER_TYPE: Returned as-is.
B_BINDER_HANDLE_TYPE: Returns binder proxy.
B_WEAK_BINDER_TYPE: Attempts to promote to strong pointer.
B_WEAK_BINDER_HANDLE_TYPE: Retrieve proxy and attempt to promote.
B_NULL_TYPE: Returns NULL. For all other types, returns NULL and 'result' is set to the current error/status code or B_BAD_TYPE.

bool AsBool ( status_t * result = NULL ) const

Convert value to boolean.
Converts from the following types:

B_BOOL_TYPE: Returned as-is.
B_STRING_TYPE: Converted to true if "true" or numeric > 0.
B_DOUBLE_TYPE, B_FLOAT_TYPE, B_INT64_TYPE, B_BIGTIME_TYPE, B_INT32_TYPE, B_INT16_TYPE, B_INT8_TYPE: Converted to true if value is not zero.
B_ATOM_TYPE: Converted to true if address is not NULL.
B_ATOM_WEAK_TYPE: Converted to true if address is not NULL.
B_BINDER_TYPE, B_BINDER_HANDLE_TYPE, B_WEAK_BINDER_TYPE, B_WEAK_BINDER_HANDLE_TYPE: Converted to true if address is not NULL.
B_NULL_TYPE: Returns false. For all other types, returns false and 'result' is set to the current error/status code or B_BAD_TYPE.

double AsDouble ( status_t * result = NULL ) const

Convert value to double.
Converts from the following types:

B_DOUBLE_TYPE: Returned as-is.
B_STRING_TYPE: Converted using strtod().
B_FLOAT_TYPE, B_INT64_TYPE, B_BIGTIME_TYPE, B_INT32_TYPE, B_INT16_TYPE, B_INT8_TYPE: Converted to a double, losing precision as needed.
B_BOOL_TYPE: Returned a 1 or 0.
B_NULL_TYPE: Returns 0.0. For all other types, returns 0.0 and 'result' is set to the current error/status code or B_BAD_TYPE.

float AsFloat ( status_t * result = NULL ) const

Convert value to float.
Converts from the following types:

B_FLOAT_TYPE: Returned as-is.
B_STRING_TYPE: Converted using strtod().
B_DOUBLE_TYPE, B_INT64_TYPE, B_BIGTIME_TYPE, B_INT32_TYPE, B_INT16_TYPE, B_INT8_TYPE: Converted to a float, losing precision as needed. No bounds checking is performed.
B_BOOL_TYPE: Returned a 1 or 0.
B_NULL_TYPE: Returns 0.0. For all other types, returns 0.0 and 'result' is set to the current error/status code or B_BAD_TYPE.

int32_t AsInt32 ( status_t * result = NULL ) const

Convert value to int32_t.
Converts from the following types:

B_INT32_TYPE: Returned as-is.
B_STRING_TYPE: Converted to a number for the formats

"[+-]nnn" -- base 10 conversion.
"[+-]0xnnn" -- base 16 conversion.
"[+-]0nnn" -- base 8 conversion.
"[aaaa]" -- packed ASCII conversion.
"'aaaa'" -- packed ASCII conversion.

B_DOUBLE_TYPE, B_FLOAT_TYPE, B_INT64_TYPE, B_BIGTIME_TYPE, B_INT16_TYPE, B_INT8_TYPE: Converted to an int32_t, losing precision as needed. No bounds checking is performed.
B_BOOL_TYPE: Returned a 1 or 0.
B_NULL_TYPE: Returns 0. For all other types, returns 0 and 'result' is set to the current error/status code or B_BAD_TYPE.

int64_t AsInt64 ( status_t * result = NULL ) const

Convert value to int64_t.
Converts from the following types:

B_INT64_TYPE: Returned as-is.
B_STRING_TYPE: Converted as per AsInt32() above.
B_DOUBLE_TYPE, B_FLOAT_TYPE, B_BIGTIME_TYPE, B_INT32_TYPE, B_INT16_TYPE, B_INT8_TYPE: Converted to an int64_t, losing precision as needed. No bounds checking is performed.
B_BOOL_TYPE: Returned a 1 or 0.
B_NULL_TYPE: Returns 0. For all other types, returns 0 and 'result' is set to the current error/status code or B_BAD_TYPE.

int32_t AsInteger ( status_t * result = NULL ) const [inline]

Deprecated:
Use AsInt32() instead.

sptr< SKeyID > AsKeyID ( status_t * result = NULL ) const

Convert value to a wrapped PalmOS KeyID, SKeyID.
We don't actually do any conversions here. If the SValue doesn't contain a valid SKeyID, we set result = B_BAD_TYPE and return NULL.

off_t AsOffset ( status_t * result = NULL ) const [inline]

Synonym for AsInt64().

SValue & Assign ( type_code type,

const void * data,

size_t len

)

SValue & Assign ( const SValue & o )

ssize_t AsSSize ( status_t * result = NULL ) const

Convert value to a status/size code.
Result will be:

If the value's ErrorCheck() is not B_OK, this is returned.
If B_STATUS_TYPE, that error code is returned.
If AsInt32() succeeds, its value is returned. Otherwise, B_OK returned and result is set to B_BAD_TYPE. Use AsStatus() instead to only retrieve valid status codes.

status_t AsStatus ( status_t * result = NULL ) const

Convert value to a status code.
This is the same as AsSSize(), except it does not return positive integers -- in that case B_OK is returned and 'result' is set to B_BAD_TYPE. Also see StatusCheck() to retrieve the value status without performing any conversions.

SString AsString ( status_t * result = NULL ) const

Convert value to a SString.
Converts from the following types:

B_STRING_TYPE: Returned as-is.
B_DOUBLE_TYPE: Converted to a string using "%g".
B_FLOAT_TYPE: Converted to a string using "%g".
B_INT64_TYPE, B_BIGTIME_TYPE: Converted using "%Ld".
B_INT32_TYPE: Convered to a string using "%ld".
B_INT16_TYPE, B_INT8_TYPE: Converted using "%d".
B_BOOL_TYPE: Converted to the string "true" or "false".
B_NULL_TYPE: Returns "". For all other types, returns "" and 'result' is set to the current error/status code or B_BAD_TYPE.

nsecs_t AsTime ( status_t * result = NULL ) const

Convert value to nsecs_t.
Converts from the following types:

B_BIGTIME_TYPE: Returned as-is.
B_STRING_TYPE: Converted using strtoll().
B_DOUBLE_TYPE, B_FLOAT_TYPE, B_INT64_TYPE, B_INT32_TYPE, B_INT16_TYPE, B_INT8_TYPE: Converted to a nsecs_t, losing precision as needed. No bounds checking is performed.
B_BOOL_TYPE: Returned a 1 or 0.
B_NULL_TYPE: Returns 0. For all other types, returns 0 and 'result' is set to the current error/status code or B_BAD_TYPE.

wptr< SAtom > AsWeakAtom ( status_t * result = NULL ) const

Convert value to a weak SAtom pointer.
Converts from the following types:

B_ATOM_TYPE: Returned as a weak pointer.
B_ATOM_WEAK_TYPE: Returns as-is.
B_NULL_TYPE: Returns NULL. For all other types, returns NULL and 'result' is set to the current error/status code or B_BAD_TYPE.

wptr< IBinder > AsWeakBinder ( status_t * result = NULL ) const

Convert value to a weak IBinder pointer.
Converts from the following types:

B_BINDER_TYPE: Returned as a weak pointer.
B_BINDER_HANDLE_TYPE: Returns binder proxy as a weak pointer.
B_WEAK_BINDER_TYPE: Returns as-is.
B_WEAK_BINDER_HANDLE_TYPE: Returns binder proxy.
B_NULL_TYPE: Returns NULL. For all other types, returns NULL and 'result' is set to the current error/status code or B_BAD_TYPE.

SValue Atom ( const sptr< SAtom > & value ) [static]

void * BeginEditBytes ( type_code type,

size_t length,

uint32_t flags = 0

)

Start raw editing of data in value.
Only valid on values for which IsSimple() is true and IsObject() is false. Call EndEditBytes() when done.
Parameters:

[in] type The new type code to assign to the value. Must not be a value map or object type.

[in] length Number of bytes needed.

[in] flags Use B_EDIT_VALUE_DATA to make the returned buffer have the some contents as the current value, otherwise the initial contents are undefined and you must set it all yourself.

Returns:
NULL if there was an error, otherwise a pointer to a buffer of 'length' bytes.

SValue * BeginEditItem ( const SValue & key )

Direct editing of sub-items in the value.

Parameters:

key The key of the item you would like to edit. This must be a simple value, not a complex mapping.

Returns:
A pointer to the value stored inside the mapping, or NULL if key could not be found.

Note:
Only valid for a value that contains full mappings {A->B}. Be sure to call EndEditItem() when done; you must not make any other calls on this object until you have done so.

static SValue Binder ( const sptr< IBinder > & value ) [inline, static]

SValue Bool ( bool v ) [static]

status_t ByteSwap ( swap_action action )

status_t CanByteSwap ( ) const

int32_t Compare ( type_code type,

const void * data,

size_t length

) const

int32_t Compare ( const SString & str ) const


Printing
Function for printing values in a nice format.
typedef status_t(*	print_func )(const sptr< ITextOutput > &io, const SValue &val, uint32_t flags)
	SValue pretty printer function.
status_t	PrintToStream (const sptr< ITextOutput > &io, uint32_t flags=0) const
	Print the value's contents in a pretty format.
static status_t	RegisterPrintFunc (type_code type, print_func func)
	Add a new printer function for a type code.
static status_t	UnregisterPrintFunc (type_code type, print_func func=NULL)
	Remove printer function for type code.
Archiving
Reading and writing as flat byte streams.
ssize_t	Archive (const sptr< IByteOutput > &into) const
ssize_t	Archive (SParcel &into) const
ssize_t	ArchivedSize () const
ssize_t	Unarchive (const sptr< IByteInput > &from)
ssize_t	Unarchive (SParcel &from)
Type Conversions
Retrieve the value as a standard type, potentially performing a conversion.
sptr< SAtom >	AsAtom (status_t *result=NULL) const
	Convert value to a strong SAtom pointer.
sptr< IBinder >	AsBinder (status_t *result=NULL) const
	Convert value to a strong IBinder pointer.
bool	AsBool (status_t *result=NULL) const
	Convert value to boolean.
double	AsDouble (status_t *result=NULL) const
	Convert value to double.
float	AsFloat (status_t *result=NULL) const
	Convert value to float.
int32_t	AsInt32 (status_t *result=NULL) const
	Convert value to int32_t.
int64_t	AsInt64 (status_t *result=NULL) const
	Convert value to int64_t.
int32_t	AsInteger (status_t *result=NULL) const
sptr< SKeyID >	AsKeyID (status_t *result=NULL) const
	Convert value to a wrapped PalmOS KeyID, SKeyID.
off_t	AsOffset (status_t *result=NULL) const
	Synonym for AsInt64().
ssize_t	AsSSize (status_t *result=NULL) const
	Convert value to a status/size code.
status_t	AsStatus (status_t *result=NULL) const
	Convert value to a status code.
SString	AsString (status_t *result=NULL) const
	Convert value to a SString.
nsecs_t	AsTime (status_t *result=NULL) const
	Convert value to nsecs_t.
wptr< SAtom >	AsWeakAtom (status_t *result=NULL) const
	Convert value to a weak SAtom pointer.
wptr< IBinder >	AsWeakBinder (status_t *result=NULL) const
	Convert value to a weak IBinder pointer.
Basic Operations
Assignment, status, existence, etc.
SValue &	Assign (type_code type, const void *data, size_t len)
SValue &	Assign (const SValue &o)
status_t	ByteSwap (swap_action action)
status_t	CanByteSwap () const
status_t	ErrorCheck () const
	Retrieve exception-level error.
bool	IsDefined () const
	Check whether the value is not B_UNDEFINED_VALUE.
bool	IsObject () const
	Check whether this value is an object, such as a binder.
bool	IsSimple () const
	Check whether this value is a single item of the form `{WILD->A}`.
bool	IsSpecified () const
	Check whether this value is neither B_UNDEFINED_VALUE nor B_WILD_VALUE.
bool	IsWild () const
	Checking whether this value is B_WILD_VALUE.
SValue &	operator= (const SValue &o)
void	SetError (status_t error)
	Set an exception-level error code.
status_t	StatusCheck () const
	Return status of the value.
void	Swap (SValue &with)
	Exchange contents of 'this' and 'with'.
void	Undefine ()
	Set value to B_UNDEFINED_VALUE.
static void	MoveAfter (SValue to, SValue from, size_t count=1)
	Move value forward in memory (for implementation of BMoveAfter).
static void	MoveBefore (SValue to, SValue from, size_t count=1)
	Move value backward in memory (for implementation of BMoveBefore).
Raw Data Operations
Operations on the value as a raw blob of data with a type code. Note that these are not value for objects containing anything besides simple values. That is, values that are only the single mapping `{WILD->data}`.
void *	BeginEditBytes (type_code type, size_t length, uint32_t flags=0)
	Start raw editing of data in value.
const void *	Data (type_code type, size_t *inoutMinLength) const
	Retrieve data if value is type and length given.
const void *	Data (type_code type, size_t length) const
	Return the data if the value is the exact given type and length.
const void *	Data () const
	Return raw data in the value.
status_t	EndEditBytes (ssize_t final_length=-1)
	Finish raw editing after previously calling BeginEditBytes().
size_t	Length () const
	Return number of bytes of data in the value.
void	Pool ()
	Make sure value's data is in the SSharedBuffer pool.
status_t	SetType (type_code newType)
	Change this value's type code.
const SSharedBuffer *	SharedBuffer () const
	Return raw value data as a SSharedBuffer.
type_code	Type () const
	Return type code of data in this value.
Mapping Operations
Working with an SValue as structured data.
SValue *	BeginEditItem (const SValue &key)
	Direct editing of sub-items in the value.
int32_t	CountItems () const
	Count the number of mappings in the value.
void	EndEditItem (SValue *item)
	Finish sub-item editing after previously calling BeginEditItem().
void	GetKeyIndices (const SValue keys, size_t outIndices, size_t count)
	Given an array keys of values, returns their indices in this's value mapping.
status_t	GetNextItem (void *cookie, SValue out_key, SValue *out_value) const
	Iterate over the mappings in the value.
bool	HasItem (const SValue &key, const SValue &value=B_UNDEFINED_VALUE) const
	Check whether this value contains the given mapping.
SValue &	Inherit (const SValue &from, uint32_t flags=0)
	Apply mappings underneath this value.
const SValue	InheritCopy (const SValue &from, uint32_t flags=0) const
	Non-destructive version of Inherit().
SValue &	Join (const SValue &from, uint32_t flags=0)
	Combine contents to two values together.
const SValue	JoinCopy (const SValue &from, uint32_t flags=0) const
	Non-destructive version of Join().
SValue &	JoinItem (const SValue &key, const SValue &value, uint32_t flags=0)
	Convenience function for overlaying a single map item.
SValue	Keys () const
	Get the keys from this value.
SValue &	MapValues (const SValue &from, uint32_t flags=0)
	Perform a value remapping operation.
const SValue	MapValuesCopy (const SValue &from, uint32_t flags=0) const
	Non-destructive version of MapValues().
const SValue	operator * (const SValue &o) const
	Synonym for MapValuesCopy().
SValue &	operator *= (const SValue &o)
	Synonym for MapValues().
const SValue	operator+ (const SValue &o) const
	Synonym for JoinCopy().
SValue &	operator+= (const SValue &o)
	Synonym for Join().
const SValue	operator- (const SValue &o) const
	Synonym for RemoveCopy().
SValue &	operator-= (const SValue &o)
	Synonym for Remove().
const SValue &	operator[] (const static_large_string_value &key) const
	Synonym for ValueFor().
const SValue &	operator[] (const static_small_string_value &key) const
	Synonym for ValueFor().
const SValue &	operator[] (int32_t index) const
	Synonym for ValueFor().
const SValue &	operator[] (const SString &key) const
	Synonym for ValueFor().
const SValue &	operator[] (const char *key) const
	Synonym for ValueFor().
const SValue &	operator[] (const SValue &key) const
	Synonym for ValueFor().
SValue &	Overlay (const SValue &from, uint32_t flags=0)
	Apply mappings on top of this value.
const SValue	OverlayCopy (const SValue &from, uint32_t flags=0) const
	Non-destructive version of Overlay().
SValue &	Remove (const SValue &from, uint32_t flags=0)
	Remove mappings from this value.
const SValue	RemoveCopy (const SValue &from, uint32_t flags=0) const
	Non-destructive version of Remove().
status_t	RemoveItem (const SValue &key, const SValue &value=B_WILD_VALUE)
	Convenience for Remove() of a single item/mapping.
status_t	RenameItem (const SValue &old_key, const SValue &new_key)
	Change the name of a key in the value.
const SValue &	ReplaceValues (const SValue values, const size_t indices, size_t count)
	Batch replace the values of a set of mappings.
SValue &	Retain (const SValue &from, uint32_t flags=0)
	Keep mappings in this value.
const SValue	RetainCopy (const SValue &from, uint32_t flags=0) const
	Non-destructive version of Retain().
const SValue &	ValueFor (const static_large_string_value &str) const
	Optimization of ValueFor() for static values.
const SValue &	ValueFor (const static_small_string_value &str) const
	Optimization of ValueFor() for static values.
const SValue &	ValueFor (int32_t index) const
	Optimization of ValueFor() for integers.
const SValue &	ValueFor (const SString &str) const
	Optimization of ValueFor() for SString.
const SValue &	ValueFor (const char *str) const
	Optimization of ValueFor() for raw character strings.
const SValue &	ValueFor (const SValue &key) const
	Optimization of ValueFor() with default flags.
const SValue	ValueFor (const SValue &key, uint32_t flags) const
	Look up a key in this value.
Comparison
The common SValue comparison operation is a quick binary compare of its type code and data. Not only is this fast, but the way values are compared is type-independent and thus will never change. The Compare() method and all comparison operators use this approach.
int32_t	Compare (type_code type, const void *data, size_t length) const
int32_t	Compare (const SString &str) const
int32_t	Compare (const char *str) const
int32_t	Compare (const SValue &o) const
int32_t	LexicalCompare (const SValue &o) const
	Perform a type-dependent comparison between two values.
bool	operator!= (const static_large_string_value &str) const
bool	operator!= (const static_small_string_value &str) const
bool	operator!= (const SString &str) const
bool	operator!= (const char *str) const
bool	operator!= (const SValue &o) const
bool	operator< (const static_large_string_value &str) const
bool	operator< (const static_small_string_value &str) const
bool	operator< (const SString &str) const
bool	operator< (const char *str) const
bool	operator< (const SValue &o) const
bool	operator<= (const static_large_string_value &str) const
bool	operator<= (const static_small_string_value &str) const
bool	operator<= (const SString &str) const
bool	operator<= (const char *str) const
bool	operator<= (const SValue &o) const
bool	operator== (const static_large_string_value &str) const
bool	operator== (const static_small_string_value &str) const
bool	operator== (const SString &str) const
bool	operator== (const char *str) const
bool	operator== (const SValue &o) const
bool	operator> (const static_large_string_value &str) const
bool	operator> (const static_small_string_value &str) const
bool	operator> (const SString &str) const
bool	operator> (const char *str) const
bool	operator> (const SValue &o) const
bool	operator>= (const static_large_string_value &str) const
bool	operator>= (const static_small_string_value &str) const
bool	operator>= (const SString &str) const
bool	operator>= (const char *str) const
bool	operator>= (const SValue &o) const
Typed Data Access
Retrieve data in value as a specific type, not performing conversion. (These functions fail if the value is not exactly the requested type.)
status_t	GetAtom (sptr< SAtom > *atom) const
status_t	GetBinder (sptr< IBinder > *obj) const
status_t	GetBool (bool *val) const
status_t	GetDouble (double *a_double) const
status_t	GetFloat (float *a_float) const
status_t	GetInt16 (int16_t *val) const
status_t	GetInt32 (int32_t *val) const
status_t	GetInt64 (int64_t *val) const
status_t	GetInt8 (int8_t *val) const
status_t	GetKeyID (sptr< SKeyID > *keyid) const
status_t	GetStatus (status_t *val) const
status_t	GetString (SString *a_string) const
status_t	GetString (const char **a_string) const
status_t	GetTime (nsecs_t *val) const
status_t	GetWeakAtom (wptr< SAtom > *atom) const
status_t	GetWeakBinder (wptr< IBinder > *obj) const
Constructors for Data
These constructors are used to create values containing a single piece of data of various types, which is implicitly the mapping `{WILD->data}`.
	SValue (const sptr< SKeyID > &binder)
	SValue (const wptr< IBinder > &binder)
	SValue (const sptr< IBinder > &binder)
	SValue (const static_large_string_value &str)
	SValue (const static_small_string_value &str)
	SValue (const SString &str)
	SValue (const char *str)
	SValue (int32_t num)
	SValue (type_code type, const SSharedBuffer *buffer)
	SValue (type_code type, const void *data, size_t len)
Constructors for Mappings
These constructors are used to create values containing a single explicit maping.
	SValue (const SValue &key, const SValue &value, uint32_t flags, size_t numMappings)
	SValue (const SValue &key, const SValue &value, uint32_t flags)
	SValue (const SValue &key, const SValue &value)
Constructor and Destructor
	SValue (const SValue &o)
	SValue ()
	~SValue ()
	NOTE THAT THE DESTRUCTOR IS NOT VIRTUAL!
Creating Data Values
These static functions allow you to build SValues of various standard types. Note that it is bette to use SSimpleValue for int8_t, int16_t, int32_t, bool, and float types, and SSimpleStatusValue for status_t.
static SValue	Atom (const sptr< SAtom > &value)
static SValue	Binder (const sptr< IBinder > &value)
static SValue	Bool (bool v)
static SValue	Double (double value)
static SValue	Float (float v)
static SValue	Int16 (int16_t v)
static SValue	Int32 (int32_t v)
static SValue	Int64 (int64_t value)
static SValue	Int8 (int8_t v)
static SValue	KeyID (const sptr< SKeyID > &value)
static SValue	Offset (off_t value)
static SValue	SSize (ssize_t value)
static SValue	Status (status_t error)
static SValue	String (const SString &value)
static SValue	String (const char *value)
static SValue	Time (nsecs_t value)
static SValue	WeakAtom (const wptr< SAtom > &value)
static SValue	WeakBinder (const wptr< IBinder > &value)
Creating Special Values
Convenience functions to access special value types.
static const SValue &	Null ()
	The null value, synonym for B_NULL_VALUE.
static const SValue &	Undefined ()
	Not-a-value, synonym for B_UNDEFINED_VALUE.
static const SValue &	Wild ()
	The all-encompassing value, synonym for B_WILD_VALUE.
Static Public Member Functions
static const SValue &	LookupConstantValue (int32_t index)
	This is for internal use, do not use directly.
Friends
class	BValueMap

SValue Class Reference [Utility Classes and Functions]

Detailed Description

Printing

Archiving

Type Conversions

Basic Operations

Raw Data Operations

Mapping Operations

Comparison

Typed Data Access

Constructors for Data

Constructors for Mappings

Constructor and Destructor

Creating Data Values

Creating Special Values

Static Public Member Functions

Friends

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

SValue Class Reference
[Utility Classes and Functions]