# C++ binding

The package contains two Rcpp functions, which bind directly to the C++ implementation of the flexible polyline encoding. These functions target a tight interface from C++ to R and reflect the arguments and return values of their counterparts (`hf::encode_polyline` and `hf::decode_polyline`) in the C++ implementation.

## Encode

Encoding a line is straight forward by passing a matrix (column order is longitude, latitude) with its coordinates to `encode()`. The default precision value is set to `5`. If a matrix with two columns is provided, the third dimension is automatically set to `"ABSENT"`:

    library(flexpolyline)

    line2d <- matrix(
      c(8.69821, 50.10228,
        8.69567, 50.10201,
        8.69150, 50.10063,
        8.68752, 50.09878),
      ncol = 2, byrow = TRUE
    )

    (encodes2d <- encode(line2d, precision = 5))
    #> [1] "BFoz5xJ67i1B1B7PzIhaxL7Y"

If a matrix with three columns is passed, a line with a third dimension is encoded. The type of the third dimension can be passed to the encoding and supports the following selection, that are specified via an integer value via the `third_dim` argument:

- 0: ABSENT
- 1: LEVEL
- 2: ALTITUDE
- 3: ELEVATION (default)
- 4: RESERVED1 (not available)
- 5: RESERVED2 (not available)
- 6: CUSTOM1
- 7: CUSTOM2

By default the precision of the third dimension `third_dim_precision` is set to the same value as the precision value for the longitude and latitude dimensions.

    line3d <- matrix(
      c(8.69821, 50.10228, 10.11111,
        8.69567, 50.10201, 20.22222,
        8.69150, 50.10063, 30.33333,
        8.68752, 50.09878, 40.44444),
      ncol = 3, byrow = TRUE
    )

    (encodes3d <- encode(line3d, precision = 5, third_dim = 3, third_dim_precision = 5))
    #> [1] "B1Voz5xJ67i1Bu629B1B7Pu629BzIhau629BxL7Yu629B"

## Decode

In order to decode the lines from above, the encoded line string is passed to the `decode()` function. The function detects from the encoded string if it is a two-dimensional or three-dimensional line:

    decode(encodes2d)
    #>          LNG      LAT
    #> [1,] 8.69821 50.10228
    #> [2,] 8.69567 50.10201
    #> [3,] 8.69150 50.10063
    #> [4,] 8.68752 50.09878

In the case of a three-dimensional line, the third column is named after the name of the third dimension that was chosen during the encoding (in this example `"ELEVATION"`):

    decode(encodes3d)
    #>          LNG      LAT ELEVATION
    #> [1,] 8.69821 50.10228  10.11111
    #> [2,] 8.69567 50.10201  20.22222
    #> [3,] 8.69150 50.10063  30.33333
    #> [4,] 8.68752 50.09878  40.44444

## References

- Flexible Polyline Encoding by HERE
- Encoded Polyline Algorithm Format
- Inspired by the googlePolylines package