Struct SingleId 

pub struct SingleId { /* private fields */ }

SingleIdは標準的な時空間 ID を表す型。

内部的には下記のような構造体で構成されている。

この型は PartialOrd / Ord を実装していますが、これは主にBTreeSet や BTreeMap などの順序付きコレクションでの格納・探索用であり、実際の空間的な「大小」を意味するものではない。

pub struct SingleId {
    z: u8,
    f: i32,
    x: u32,
    y: u32,
    temporal_id: TemporalId,
}

Implementations

impl SingleId

pub fn new(z: u8, f: i32, x: u32, y: u32) -> Result<SingleId, Error>

指定された値から SingleId を作成する。このコンストラクタは、与えられた z, f, x, y が 各ズームレベルにおける範囲内にあるかを検証し、範囲外の場合は Error を返す。

パラメータ

• z — ズームレベル（0–MAX_ZOOM_LEVELの範囲が有効）
• f — Fインデックス（鉛直方向）
• x — Xインデックス（東西方向）
• y — Yインデックス（南北方向）

バリデーション

• z が MAX_ZOOM_LEVEL を超える場合、SpatialIdError::ZOutOfRange を返す。
• f がズームレベル z に対する F_MIN[z]..=F_MAX[z] の範囲外の場合、 SpatialIdError::FOutOfRange を返す。
• x または y が 0..=XY_MAX[z] の範囲外の場合、 それぞれ SpatialIdError::XOutOfRange、SpatialIdError::YOutOfRange を返す。

IDの作成:

let id = SingleId::new(5, 3, 2, 10).unwrap();
assert_eq!(id.to_string(), "5/3/2/10".to_string());

次元の範囲外の検知:

let id = SingleId::new(3, 3, 2, 10);
assert_eq!(id, Err(SpatialIdError::YOutOfRange{z:3,y:10}.into()));

ズームレベルの範囲外の検知:

let id = SingleId::new(68, 3, 2, 10);
assert_eq!(id, Err(SpatialIdError::ZOutOfRange { z:68 }.into()));

pub unsafe fn new_unchecked(z: u8, f: i32, x: u32, y: u32) -> SingleId

検証を行わずに SingleId を作成する。

この関数は SingleId::new と異なり、与えられた z, f, x, y に対して一切の範囲チェックや整合性チェックを行わない。そのため、高速に ID を生成できるが、不正なパラメータを与えた場合の動作は未定義である。

注意

呼び出し側は、以下をすべて満たすことを保証しなければならない。

• z が有効なズームレベル（0–MAX_ZOOM_LEVEL）であること
• f が与えられた z に応じて F_MIN[z]..=F_MAX[z] の範囲内であること
• x および y が 0..=XY_MAX[z] の範囲内であること

これらが保証されない場合、パニック・不正メモリアクセス・未定義動作を引き起こす可能性がある。

// パラメータが妥当であることを呼び出し側が保証する必要がある
let id = unsafe { SingleId::new_unchecked(5, 3, 2, 10) };

assert_eq!(id.z(), 5u8);
assert_eq!(id.f(), 3i32);
assert_eq!(id.x(), 2u32);
assert_eq!(id.y(), 10u32);

impl SingleId

pub fn random() -> Self

ランダムなSingleIdを作成する

pub fn random_at(z: u8) -> Self

特定のズームレベルにおいて、ランダムなSingleIdを作成する

pub fn random_within(z_range: RangeInclusive<u8>) -> Self

特定のズームレベル間において、ランダムなSingleIdを作成する

pub fn random_using<R: Rng>(rng: &mut R) -> Self

外部から渡された乱数生成器を使って、全ズーム範囲からランダムな SingleId を生成します。

pub fn random_at_using<R: Rng>(rng: &mut R, z: u8) -> Self

外部から渡された乱数生成器を使って、指定ズームのランダムな SingleId を生成します。

pub fn random_within_using<R: Rng>( rng: &mut R, z_range: RangeInclusive<u8>, ) -> Self

外部から渡された乱数生成器を使って、指定ズーム範囲のランダムな SingleId を生成します。

z_range の終端は MAX_ZOOM_LEVEL でクリップされ、start > end の場合は end を採用します。

impl SingleId

pub fn z(&self) -> u8

この SingleId が保持しているズームレベル z を返します。

let id = SingleId::new(5, 3, 2, 10).unwrap();
assert_eq!(id.z(), 5u8);

pub fn f(&self) -> i32

この SingleId が保持している F インデックス f を返します。

let id = SingleId::new(5, 3, 2, 10).unwrap();
assert_eq!(id.f(), 3i32);

pub fn x(&self) -> u32

この SingleId が保持している X インデックス x を返します。

let id = SingleId::new(5, 3, 2, 10).unwrap();
assert_eq!(id.x(), 2u32);

pub fn y(&self) -> u32

この SingleId が保持している Y インデックス y を返します。

let id = SingleId::new(5, 3, 2, 10).unwrap();
assert_eq!(id.y(), 10u32);

pub fn set_f(&mut self, value: i32) -> Result<(), Error>

F インデックスを更新します。

与えられた value が、現在のズームレベル z に対応する F_MIN[z]..=F_MAX[z] の範囲内にあるかを検証し、範囲外の場合は Error を返します。

パラメータ

• value — 新しい F インデックス

バリデーション

• value が許容範囲外の場合、SpatialIdError::FOutOfRange を返します。

正常な更新:

let mut id = SingleId::new(5, 3, 2, 10).unwrap();
id.set_f(4).unwrap();
assert_eq!(id.f(), 4);

範囲外の検知:

let mut id = SingleId::new(3, 3, 2, 7).unwrap();
let result = id.set_f(999);
assert!(matches!(result, Err(Error::SpatialId(SpatialIdError::FOutOfRange { z: 3, f: 999 }))));

pub fn set_x(&mut self, value: u32) -> Result<(), Error>

X インデックスを更新します。

与えられた value が、現在のズームレベル z に対応する 0..=XY_MAX[z] の範囲内にあるかを検証し、範囲外の場合は Error を返します。

パラメータ

• value — 新しい X インデックス

バリデーション

• value が許容範囲外の場合、SpatialIdError::XOutOfRange を返します。

正常な更新:

let mut id = SingleId::new(5, 3, 2, 10).unwrap();
id.set_x(4).unwrap();
assert_eq!(id.x(), 4);

範囲外の検知

let mut id = SingleId::new(3, 3, 2, 7).unwrap();
let result = id.set_x(999);
assert!(matches!(result, Err(Error::SpatialId(SpatialIdError::XOutOfRange { z: 3, x: 999 }))));

pub fn set_y(&mut self, value: u32) -> Result<(), Error>

Y インデックスを更新します。

与えられた value が、現在のズームレベル z に対応する 0..=XY_MAX[z] の範囲内にあるかを検証し、範囲外の場合は Error を返します。

パラメータ

• value — 新しい Y インデックス

バリデーション

• value が許容範囲外の場合、SpatialIdError::YOutOfRange を返します。

正常な更新

let mut id = SingleId::new(5, 3, 2, 10).unwrap();
id.set_y(8).unwrap();
assert_eq!(id.y(), 8);

範囲外の検知

let mut id = SingleId::new(3, 3, 2, 7).unwrap();
let result = id.set_y(999);
assert!(matches!(result, Err(Error::SpatialId(SpatialIdError::YOutOfRange { z: 3, y: 999 }))));

pub fn spatial_children_at_zoom( &self, target_z: u8, ) -> Result<impl Iterator<Item = SingleId>, Error>

指定したズームレベル target_z に細分化した、この SingleId を含むすべての子 SingleId を生成します。

パラメータ

• target_z — 生成したい子 SingleId のズームレベル

バリデーション

• target_z が現在のズームレベルより浅い場合は、SpatialIdError::ZoomLevelTransitionOutOfRange を返します。
• target_z が本クレートで扱える最大ズームレベルを超える場合は、SpatialIdError::ZOutOfRange を返します。

1段深いズームへの細分化

let id = SingleId::new(3, 3, 2, 7).unwrap();

// target_z = 4 のため F, X, Y はそれぞれ 2 分割される
let children: Vec<_> = id.spatial_children_at_zoom(4).unwrap().collect();

assert_eq!(children.len(), 8); // 2 × 2 × 2

// 最初の要素を確認（f, x, y の下限側）
let first = &children[0];
assert_eq!(first.z(), 4);
assert_eq!(first.f(), 3 * 2);   // 2
assert_eq!(first.x(), 2 * 2);   // 6
assert_eq!(first.y(), 7 * 2);   // 8

現在より浅いズームを指定した場合

let id = SingleId::new(3, 3, 2, 7).unwrap();
let result = id.spatial_children_at_zoom(2);
assert!(matches!(result, Err(Error::SpatialId(SpatialIdError::ZoomLevelTransitionOutOfRange { current_z: 3, target_z: 2 }))));

pub fn spatial_parent_at_zoom(&self, target_z: u8) -> Result<SingleId, Error>

指定したズームレベル target_z に縮約した、この SingleId の親 SingleId を返します。

パラメータ

• target_z — 取得したい親 SingleId のズームレベル

バリデーション

• target_z が現在のズームレベルより深い場合は、SpatialIdError::ZoomLevelTransitionOutOfRange を返します。
• target_z が本クレートで扱える最大ズームレベルを超える場合は、SpatialIdError::ZOutOfRange を返します。

1段浅いズームへの縮約

let id = SingleId::new(4, 6, 9, 14).unwrap();

let parent = id.spatial_parent_at_zoom(3).unwrap();

assert_eq!(parent.z(), 3u8);
assert_eq!(parent.f(), 3i32);
assert_eq!(parent.x(), 4u32);
assert_eq!(parent.y(), 7u32);

Fが負の場合の挙動

let id = SingleId::new(4, -1, 8, 12).unwrap();

let parent = id.spatial_parent_at_zoom(3).unwrap();

assert_eq!(parent.z(), 3u8);
assert_eq!(parent.f(), -1i32);
assert_eq!(parent.x(), 4u32);
assert_eq!(parent.y(), 6u32);

現在より深いズームを指定した場合:

let id = SingleId::new(3, 3, 2, 7).unwrap();
let result = id.spatial_parent_at_zoom(4);
assert!(matches!(result, Err(Error::SpatialId(SpatialIdError::ZoomLevelTransitionOutOfRange { current_z: 3, target_z: 4 }))));

Trait Implementations

impl Clone for SingleId

fn clone(&self) -> SingleId

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SingleId

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SingleId

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for SingleId

fn fmt(&self, f: &mut Formatter<'_>) -> Result

SingleId を文字列形式で表示する。

形式は "{z}/{f}/{x}/{y}"。

let id = SingleId::new(4, 6, 9, 10).unwrap();
let s = format!("{}", id);
assert_eq!(s, "4/6/9/10");

impl Eq for SingleId

impl From<&SingleId> for FlexId

fn from(value: &SingleId) -> Self

Converts to this type from the input type.

impl From<&SingleId> for RangeId

fn from(id: &SingleId) -> Self

Converts to this type from the input type.

impl From<SingleId> for FlexId

fn from(value: SingleId) -> Self

Converts to this type from the input type.

impl From<SingleId> for RangeId

fn from(id: SingleId) -> Self

Converts to this type from the input type.

impl Hash for SingleId

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoFlexIds for SingleId

type IntoIter = Once<FlexId>

fn into_flex_ids(self) -> Self::IntoIter

所有権ごと FlexId の列へ変換する。

impl IntoSingleIds for SingleId

type IntoIter = Once<SingleId>

fn into_single_ids(self) -> Self::IntoIter

所有権ごと SingleId の列へ変換する。

impl IterFlexIds for SingleId

type Iter<'a> = Once<FlexId>

fn iter_flex_ids(&self) -> Self::Iter<'_>

参照から FlexId の列を列挙する。

impl IterSingleIds for SingleId

type Iter<'a> = Once<SingleId>

fn iter_single_ids(&self) -> Self::Iter<'_>

参照から SingleId の列を列挙する。

impl Ord for SingleId

fn cmp(&self, other: &SingleId) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for SingleId

fn eq(&self, other: &SingleId) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for SingleId

fn partial_cmp(&self, other: &SingleId) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for SingleId

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl SpatialId for SingleId

fn move_f(&mut self, by: i32) -> Result<(), Error>

指定したインデックス差 by に基づき、この SingleId を垂直上下方向に動かします。

パラメータ

• by — インデックス差

バリデーション

• Fインデックスが範囲外になる場合はSpatialIdError::FOutOfRangeを返します

移動

let mut id = SingleId::new(4, 6, 9, 10).unwrap();
assert_eq!(id.f(), 6);

let _ = id.move_f(-10).unwrap();
assert_eq!(id.f(), -4);

範囲外の検知によるエラー

let mut id = SingleId::new(4, 6, 9, 10).unwrap();
assert_eq!(id.f(), 6);
assert_eq!(id.move_f(50), Err(SpatialIdError::FOutOfRange { z: 4, f: 56 }.into()));

fn move_x(&mut self, by: i32)

指定したインデックス差 by に基づき、この SingleId を東西方向に動かします。WEBメルカトル図法において、東西方向は循環しているためどのような値を指定してもエラーは発生しません。

パラメータ

• by — インデックス差

移動

let mut id = SingleId::new(4, 6, 9, 10).unwrap();
assert_eq!(id.x(), 9);

let _ = id.move_x(-3);
assert_eq!(id.x(), 6);

循環による移動

let mut id = SingleId::new(4, 6, 9, 10).unwrap();
assert_eq!(id.x(), 9);

let _ = id.move_x(100);
assert_eq!(id.x(), 13);

fn move_y(&mut self, by: i32) -> Result<(), Error>

指定したインデックス差 by に基づき、この SingleId を南北方向に動かします。

パラメータ

• by — インデックス差

バリデーション

• Yインデックスが範囲外になる場合はSpatialIdError::YOutOfRangeを返します

移動

let mut id = SingleId::new(4, 6, 9, 10).unwrap();
assert_eq!(id.y(), 10);

let _ = id.move_y(-3).unwrap();
assert_eq!(id.y(), 7);

範囲外の検知によるエラー

let mut id = SingleId::new(4, 6, 9, 10).unwrap();
assert_eq!(id.y(), 10);
assert_eq!(id.move_y(-20), Err(SpatialIdError::YOutOfRange { z: 4, y: 0 }.into()));

fn spatial_center(&self) -> Coordinate

SingleId の中心座標をCoordinate型で返します。

中心座標は空間IDの最も外側の頂点の8点の平均座標です。現実空間における空間IDは完全な直方体ではなく、緯度や高度によって歪みが発生していることに注意する必要があります。

let id = SingleId::new(4, 6, 9, 14).unwrap();
let center: Coordinate = id.spatial_center();
println!("{:?}", center);
// Coordinate { latitude: -81.09321385260839, longitude: 33.75, altitude: 13631488.0 }

fn spatial_vertices(&self) -> [Coordinate; 8]

SingleId の最も外側の頂点の8点の座標をCoordinate型の配列として返します。

現実空間における空間IDは完全な直方体ではなく、緯度や高度によって歪みが発生していることに注意する必要があります。

let id = SingleId::new(4, 6, 9, 14).unwrap();
let vertices: [Coordinate; 8] = id.spatial_vertices();
println!("{:?}", vertices);

 //[Coordinate { latitude: -79.17133464081945, longitude: 22.5, altitude: 12582912.0 }, Coordinate { latitude: -79.17133464081945, longitude: 45.0, altitude: 12582912.0 }, Coordinate { latitude: -82.67628497834903, longitude: 22.5, altitude: 12582912.0 }, Coordinate { latitude: -82.67628497834903, longitude: 45.0, altitude: 12582912.0 }, Coordinate { latitude: -79.17133464081945, longitude: 22.5, altitude: 14680064.0 }, Coordinate { latitude: -79.17133464081945, longitude: 45.0, altitude: 14680064.0 }, Coordinate { latitude: -82.67628497834903, longitude: 22.5, altitude: 14680064.0 }, Coordinate { latitude: -82.67628497834903, longitude: 45.0, altitude: 14680064.0 }]

fn length_f_meters(&self) -> f64

その空間IDのＦ方向の長さをメートル単位で計算する関数

fn length_x_meters(&self) -> f64

その空間IDのX方向の長さをメートル単位で計算する関数

fn length_y_meters(&self) -> f64

その空間IDのY方向の長さをメートル単位で計算する関数

fn f_min(&self) -> i32

ズームレベルにおける最小のFインデックスを返す。

fn f_max(&self) -> i32

ズームレベルにおける最大のFインデックスを返す。

fn x_max(&self) -> u32

ズームレベルにおける最大のXインデックスを返す。

fn y_max(&self) -> u32

ズームレベルにおける最大のYインデックスを返す。

fn temporal(&self) -> &TemporalId

時間 ID を参照で返す。

fn temporal_mut(&mut self) -> &mut TemporalId

時間 ID を可変参照で返す。

fn x_min(&self) -> u32

ズームレベルにおける最小のXインデックスを返す。全てのIDにおいて必ず0を返す。

fn y_min(&self) -> u32

ズームレベルにおける最小のYインデックスを返す。全てのIDにおいて必ず0を返す。

impl StructuralPartialEq for SingleId