# Class RangingUpdate

java.lang.Object
com.codename1.nearby.ranging.RangingUpdate

public final class RangingUpdate extends Object

One measurement of where the peer is, delivered to `RangingListener.updated(RangingUpdate)` on the EDT.

Every field except the timestamp is optional, and they drop out independently: a peer directly behind the phone commonly reports a distance with no direction, and a peer at the edge of range reports neither. Guard each read with its `has` method rather than assuming a sentinel value.

    public void updated(RangingUpdate u) {
        if (u.hasDistance()) {
            label.setText(String.format("%.1f m", u.getDistance(RangingUnit.METERS)));
        }
        if (u.hasDirection()) {
            arrow.setAngle(u.getAzimuth());
        }
    }

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RangingUpdate(boolean hasDistance, double distanceMeters, boolean hasDirection, double azimuth, boolean hasElevation, double elevation, float[] vector, long timestamp)`
  Ports construct these; application code receives them through `RangingListener`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `double`
  `getAzimuth()`
  The horizontal angle to the peer in degrees.
  `float[]`
  `getDirectionVector()`
  The platform's raw unit direction vector as `{x, y, z}` -- x to the right, y up, z toward the user, so the forward direction is negative z.
  `double`
  `getDistance(RangingUnit unit)`
  The straight-line distance to the peer, in the unit you name.
  `double`
  `getElevation()`
  The vertical angle to the peer in degrees, in the range -90 to 90, where positive is above the device.
  `long`
  `getTimestamp()`
  `System.currentTimeMillis()` at the moment the port received this measurement.
  `boolean`
  `hasDirection()`
  `true` when this update carries a horizontal direction.
  `boolean`
  `hasDistance()`
  `true` when this update carries a distance measurement.
  `boolean`
  `hasElevation()`
  `true` when this update carries a vertical direction.
  `String`
  `toString()`
  Returns a string representation of the object.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### RangingUpdate

    public RangingUpdate(boolean hasDistance, double distanceMeters, boolean hasDirection, double azimuth, boolean hasElevation, double elevation, float[] vector, long timestamp)

    Ports construct these; application code receives them through `RangingListener`.

    ###### Parameters

    - `hasDistance`: whether this update carries a distance
    - `distanceMeters`: the distance in meters, ignored when `hasDistance` is false
    - `hasDirection`: whether this update carries an azimuth
    - `azimuth`: horizontal angle in degrees, ignored when `hasDirection` is false
    - `hasElevation`: whether this update carries an elevation
    - `elevation`: vertical angle in degrees, ignored when `hasElevation` is false
    - `vector`: the platform's raw unit direction vector, or `null`
    - `timestamp`: `System.currentTimeMillis()` when the port received the measurement

- ## Method Details

  - ### hasDistance

    public boolean hasDistance()
    `true` when this update carries a distance measurement.

  - ### getDistance

    public double getDistance(RangingUnit unit)

    The straight-line distance to the peer, in the unit you name.

    Undefined when `hasDistance()` is `false` -- check first. There is no zero-argument form on purpose; see `RangingUnit`.

    ###### Parameters

    - `unit`: the unit to read the distance in

    ###### Returns

    the distance expressed in `unit`

  - ### hasDirection

    public boolean hasDirection()
    `true` when this update carries a horizontal direction.

  - ### getAzimuth

    public double getAzimuth()

    The horizontal angle to the peer in degrees. Zero is straight ahead -- out of the top of a phone held upright -- and positive is to the right.

    Undefined when `hasDirection()` is `false`.

    The range is platform-dependent, and the difference is meaningful. Apple reports a unit direction vector, which the port folds with `atan2(x, -z)` into -180 to 180 -- so it distinguishes a peer in front from one directly behind. Jetpack UWB reports the angle itself, in degrees, but only over -90 to 90, which does not. Code that needs to know which side of the device a peer is on cannot get that from azimuth alone on Android.

    `getDirectionVector()` still hands back Apple's untouched vector for code that wants it.

  - ### hasElevation

    public boolean hasElevation()
    `true` when this update carries a vertical direction.

  - ### getElevation

    public double getElevation()

    The vertical angle to the peer in degrees, in the range -90 to 90, where positive is above the device.

    Undefined when `hasElevation()` is `false`. Fewer devices report elevation than azimuth, so this drops out on its own.

  - ### getDirectionVector

    public float[] getDirectionVector()

    The platform's raw unit direction vector as `{x, y, z}` -- x to the right, y up, z toward the user, so the forward direction is negative z. iOS only; `null` everywhere else and `null` on iOS whenever `hasDirection()` is `false`.

    Prefer `getAzimuth()` and `getElevation()`, which are derived from this on iOS and reported natively on Android, so they work on both. A fresh copy is returned each call.

  - ### getTimestamp

    public long getTimestamp()
    `System.currentTimeMillis()` at the moment the port received this measurement. The platforms disagree on what clock their own timestamps use -- Android reports elapsed realtime nanoseconds and iOS reports nothing at all -- so this is stamped on arrival rather than translated, and is comparable only with other values from this same clock.

  - ### toString

    public String toString()
    Description copied from class: `Object`
    Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + '@' + Integer.toHexString(hashCode())
    Overrides:
      `toString` in class `Object`