Struct RangeId 

pub struct RangeId { /* private fields */ }

RangeIdは空間IDの範囲表現を表す型です。

各インデックスを範囲で指定することができます。各次元の範囲を表す配列の順序には意味を持ちません。内部的には下記のような構造体で構成されており、各フィールドをプライベートにすることで、ズームレベルに依存するインデックス範囲やその他のバリデーションを適切に適用することができます。

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

pub struct RangeId {
    z: u8,
    f: [i32; 2],
    x: [u32; 2],
    y: [u32; 2],
}

Implementations

impl RangeId

pub fn new( z: u8, f: [i32; 2], x: [u32; 2], y: [u32; 2], ) -> Result<RangeId, Error>

指定された値から RangeId を構築します。 与えられた z, f1, f2, x1, x2, y1, y2 が 各ズームレベルにおける範囲内にあるかを検証し、範囲外の場合は Error を返します。

　各次元の与えられた2つの値は自動的に昇順に並び替えられ、 常に [min, max] の形で内部に保持されます。

パラメータ

• z — ズームレベル（0–63の範囲が有効）
• f1 — 鉛直方向範囲の端のFインデックス
• f2 — 鉛直方向範囲の端のFインデックス
• x1 — 東西方向範囲の端のXインデックス
• x2 — 東西方向範囲の端のXインデックス
• y1 — 南北方向範囲の端のYインデックス
• y2 — 南北方向範囲の端のYインデックス

バリデーション

• z が 63 を超える場合、SpatialIdError::ZOutOfRange を返します。
• f1,f2 がズームレベル z に対する F_MIN[z]..=F_MAX[z] の範囲外の場合、
  SpatialIdError::FOutOfRange を返します。
• x1,x2 または y1,y2 が 0..=XY_MAX[z] の範囲外の場合、
  それぞれ SpatialIdError::XOutOfRange、SpatialIdError::YOutOfRange を返します。

IDの作成:

let id = RangeId::new(4, [-3,6], [8,9], [5,10]).unwrap();
let s = format!("{}", id);
assert_eq!(s, "4/-3:6/8:9/5:10");

次元の範囲外の検知:

let id = RangeId::new(4, [-3,29], [8,9], [5,10]);
assert_eq!(id, Err(SpatialIdError::FOutOfRange{z:4,f:29}.into()));

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

let id = RangeId::new(68, [-3,29], [8,9], [5,10]);
assert_eq!(id, Err(SpatialIdError::ZOutOfRange { z:68 }.into()));

pub unsafe fn new_unchecked( z: u8, f: [i32; 2], x: [u32; 2], y: [u32; 2], ) -> RangeId

検証を行わずに RangeId を構築します。

この関数は RangeId::new と異なり、与えられた z, f1, f2, x1,x2, y1, y2` に対して 一切の範囲チェックや整合性チェックを行いません。 そのため、高速に ID を生成できますが、不正なパラメータを与えた場合の動作は未定義です。

注意

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

• z が有効なズームレベル（0–63）であること
• f1,f2 が与えられた z に応じて F_MIN[z]..=F_MAX[z] の範囲内であること
• x1,x2 および y1,y2 が 0..=XY_MAX[z] の範囲内であること

これらが保証されない場合、本構造体の他のメソッド（範囲を前提とした計算）が パニック・不正メモリアクセス・未定義動作を引き起こす可能性があります。

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

assert_eq!(id.z(), 5);
assert_eq!(id.f(), [-10,-5]);
assert_eq!(id.x(), [8,9]);
assert_eq!(id.y(), [5,10]);

impl RangeId

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

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

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

外部から渡された乱数生成器を使用して、指定したズームレベルでランダムにRangeIdを生成

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

外部から渡された乱数生成器を使用して、指定したズームレベル範囲内でランダムにRangeIdを生成

pub fn random() -> Self

全空間（Z=0〜MAX）からランダムにRangeIdを生成

pub fn random_at(z: u8) -> Self

指定したズームレベルでランダムにRangeIdを生成

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

指定ズーム範囲からランダムな RangeId を生成します。

内部で rand::rng() を作って random_within_using に委譲します。

impl RangeId

pub fn z(&self) -> u8

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

let id = RangeId::new(5, [-3,29], [8,9], [5,10]).unwrap();
assert_eq!(id.z(), 5u8);

pub fn f(&self) -> [i32; 2]

この RangeId が保持しているズームレベル [f1,f2] を返します。

let id = RangeId::new(5, [-3,29], [8,9], [5,10]).unwrap();
assert_eq!(id.f(), [-3i32,29i32]);

pub fn x(&self) -> [u32; 2]

この RangeId が保持しているズームレベル [x1,x2] を返します。

let id = RangeId::new(5, [-3,29], [8,9], [5,10]).unwrap();
assert_eq!(id.x(), [8u32,9u32]);

pub fn y(&self) -> [u32; 2]

この RangeId が保持しているズームレベル [y1,y2] を返します。

let id = RangeId::new(5, [-3,29], [8,9], [5,10]).unwrap();
assert_eq!(id.y(), [5u32,10u32]);

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

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

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

pub fn spatial_children_at_zoom(&self, target_z: u8) -> Result<RangeId, Error>

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

パラメータ

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

バリデーション

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

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

let id = RangeId::new(5, [-3,29], [8,9], [5,10]).unwrap();
let result = id.spatial_children_at_zoom(6).unwrap();
assert_eq!(result,  RangeId::new(6, [-6, 59], [16, 19], [10, 21] ).unwrap());

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

let id = RangeId::new(5, [-3,29], [8,9], [5,10]).unwrap();
let result = id.spatial_children_at_zoom(4);
assert!(matches!(result, Err(Error::SpatialId(SpatialIdError::ZoomLevelTransitionOutOfRange { current_z: 5, target_z: 4 }))));

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

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

パラメータ

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

バリデーション

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

1段浅いズームへの縮約

let id = RangeId::new(5, [1,29], [8,9], [5,10]).unwrap();
let parent = id.spatial_parent_at_zoom(4).unwrap();

assert_eq!(parent.z(), 4);
assert_eq!(parent.f(), [0,14]);
assert_eq!(parent.x(), [4,4]);
assert_eq!(parent.y(), [2,5]);

Fが負の場合の挙動:

let id = RangeId::new(5, [-10,-5], [8,9], [5,10]).unwrap();

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

assert_eq!(parent.z(), 4);
assert_eq!(parent.f(), [-5,-3]);
assert_eq!(parent.x(), [4,4]);
assert_eq!(parent.y(), [2,5]);

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

let id = RangeId::new(5, [-10,-5], [8,9], [5,10]).unwrap();
let result = id.spatial_parent_at_zoom(6);
assert!(matches!(result, Err(Error::SpatialId(SpatialIdError::ZoomLevelTransitionOutOfRange { current_z: 5, target_z: 6 }))));

Trait Implementations

impl Clone for RangeId

fn clone(&self) -> RangeId

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RangeId

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RangeId

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for RangeId

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

RangeId を文字列形式で表示します。

形式は "{z}/{f1}:{f2}/{x1}:{x2}/{y1}:{y2}" です。 また、次元の範囲が単体の場合は自動的にその次元がSingle表示になります。

通常時の範囲表示

let id = RangeId::new(4, [-3,6], [8,9], [5,10]).unwrap();
let s = format!("{}", id);
assert_eq!(s, "4/-3:6/8:9/5:10");

Single範囲に自動圧縮（f1=f2）

let id = RangeId::new(4, [-3,-3], [8,9], [5,10]).unwrap();
let s = format!("{}", id);
 assert_eq!(s, "4/-3/8:9/5:10");;

impl Eq for RangeId

impl From<&FlexId> for RangeId

fn from(flex_id: &FlexId) -> 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<FlexId> for RangeId

fn from(flex_id: FlexId) -> 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 RangeId

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 RangeId

type IntoIter = Box<dyn Iterator<Item = FlexId>>

fn into_flex_ids(self) -> Self::IntoIter

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

impl IntoSingleIds for RangeId

type IntoIter = Box<dyn Iterator<Item = SingleId>>

fn into_single_ids(self) -> Self::IntoIter

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

impl IterFlexIds for RangeId

type Iter<'a> = Box<dyn Iterator<Item = FlexId> + 'a>

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

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

impl IterSingleIds for RangeId

type Iter<'a> = Box<dyn Iterator<Item = SingleId> + 'a>

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

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

impl Ord for RangeId

fn cmp(&self, other: &RangeId) -> 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 RangeId

fn eq(&self, other: &RangeId) -> 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 RangeId

fn partial_cmp(&self, other: &RangeId) -> 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 RangeId

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 RangeId

fn spatial_center(&self) -> Coordinate

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

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

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

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

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

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 move_f(&mut self, by: i32) -> Result<(), Error>

F 方向に指定インデックスだけ移動する。

fn move_x(&mut self, by: i32)

X 方向に指定インデックスだけ移動する。

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

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 RangeId