January 21, 2008 PROP_NUMBER 3

### NAME

prop_number, prop_number_create_integer, prop_number_create_unsigned_integer, prop_number_copy, prop_number_size, prop_number_unsigned, prop_number_integer_value, prop_number_unsigned_integer_value, prop_number_equals, prop_number_equals_integer, prop_number_equals_unsigned_integer - numeric value property object

### LIBRARY

### SYNOPSIS

```prop_number_t` prop_number_create_integer(```int64_t val`)
```prop_number_t` prop_number_create_unsigned_integer(```uint64_t val`)
```prop_number_t` prop_number_copy(```prop_number_t number`)
```int` prop_number_size(```prop_number_t number`)
```bool` prop_number_unsigned(```prop_number_t number`)
```int64_t` prop_number_integer_value(```prop_number_t number`)
```uint64_t` prop_number_unsigned_integer_value(```prop_number_t number`)
```bool` prop_number_equals(```prop_number_t num1``, prop_number_t num2`)
```bool` prop_number_equals_integer(```prop_number_t number``, int64_t val`)
```bool` prop_number_equals_unsigned_integer(```prop_number_t number``, uint64_t val`)

### DESCRIPTION

The prop_number family of functions operate on a numeric value property object type. Values are either signed or unsigned, and promoted to a 64-bit type (int64_t or uint64_t, respectively).

It is possible to compare number objects that differ in sign. Such comparisons first test to see if each object is within the valid number range of the other:

- Signed numbers that are greater than or equal to 0 can be compared to unsigned numbers.

- Unsigned numbers that are less than or equal to the largest signed 64-bit value (```INT64_MAX`) can be compared to signed numbers.

Number objects have a different externalized representation depending on their sign:

- Signed numbers are externalized in base-10 (decimal).

- Unsigned numbers are externalized in base-16 (hexadecimal).

When numbers are internalized, the sign of the resulting number object (and thus its valid range) is determined by a set of rules evaluated in the following order:

- If the first character of the number is a `-' then the number is signed.

- If the first two characters of the number are `0x' then the number is unsigned.

- If the number value fits into the range of a signed number then the number is signed.

- In all other cases, the number is unsigned.

prop_number_create_integer(```int64_t val`)
  Create a numeric value object with the signed value ```val`. Returns ```NULL` on failure.

prop_number_create_unsigned_integer(```uint64_t val`)
  Create a numeric value object with the unsigned value ```val`. Returns ```NULL` on failure.

prop_number_copy(```prop_number_t number`)
  Copy a numeric value object. If the supplied object isn't a numeric value, ```NULL` is returned.

prop_number_size(```prop_number_t number`)
  Returns 8, 16, 32, or 64, representing the number of bits required to hold the value of the object. If the supplied object isn't a numeric value, ```NULL` is returned.

prop_number_unsigned(```prop_number_t number`)
  Returns ```true` if the numeric value object has an unsigned value.

prop_number_integer_value(```prop_number_t number`)
  Returns the signed integer value of the numeric value object. If the supplied object isn't a numeric value, zero is returned. Thus, it is not possible to distinguish between ``not a prop_number_t'' and ``prop_number_t has a value of 0''.

prop_number_unsigned_integer_value(```prop_number_t number`)
  Returns the unsigned integer value of the numeric value object. If the supplied object isn't a numeric value, zero is returned. Thus, it is not possible to distinguish between ``not a prop_number_t'' and ``prop_number_t has a value of 0''.

prop_number_equals(```prop_number_t num1``, prop_number_t num2`)
  Returns ```true` if the two numeric value objects are equivalent. If at least one of the supplied objects isn't a numeric value, ```false` is returned.

prop_number_equals_integer(```prop_number_t number``, int64_t val`)
  Returns ```true` if the object's value is equivalent to the signed value ```val`. If the supplied object isn't a numerical value or if ```val` exceeds ```INT64_MAX`, ```false` is returned.

prop_number_equals_unsigned_integer(```prop_number_t number``, uint64_t val`)
  Returns ```true` if the object's value is equivalent to the unsigned value ```val`. If the supplied object isn't a numerical value or if ```val` exceeds ```INT64_MAX`, ```false` is returned.

### SEE ALSO

prop_array(3), prop_bool(3), prop_data(3), prop_dictionary(3), prop_object(3), prop_string(3), proplib(3)

### HISTORY

The proplib property container object library first appeared in NetBSD4.0.