pub struct SafeUrl { /* private fields */ }
Expand description
Represents a SafeUrl
A SafeUrl
can be in one of two formats: nrs or xor.
aka: nrsurl or xorurl
Here is a breakdown of how name terminology is used.
case 1: safe://a.b.shinything:
public_name
() –> a.b.shinything
top_name
() –> shinything
sub_names
() –> a.b
case 2: safe://shinything:
public_name
() –> shinything
top_name
() –> shinything
sub_names
() –> None
case 3: safe://a.b.hnyynyzhjjjatqkfkjux8maaojtj8r59aphcnue6a11qgecpcebidkywmybnc
public_name
() –> a.b.hnyynyzhjjjatqkfkjux8maaojtj8r59aphcnue6a11qgecpcebidkywmybnc
top_name
() –> hnyynyzhjjjatqkfkjux8maaojtj8r59aphcnue6a11qgecpcebidkywmybnc
sub_names
() –> a.b
case 4: safe://hnyynyzhjjjatqkfkjux8maaojtj8r59aphcnue6a11qgecpcebidkywmybnc
public_name
() –> hnyynyzhjjjatqkfkjux8maaojtj8r59aphcnue6a11qgecpcebidkywmybnc
top_name
() –> hnyynyzhjjjatqkfkjux8maaojtj8r59aphcnue6a11qgecpcebidkywmybnc
sub_names
() –> None
Implementations§
source§impl SafeUrl
impl SafeUrl
This implementation performs semi-rigorous validation,
when parsing a URL using ::from_url
(), ::from_xorurl
(),
or ::from_nrsurl
().
However setters and new() do not enforce all the rules and using them with invalid input can result in serializing invalid URLs. GIGO.
As such, it is recommended to check validity by
calling SafeUrl::validate
() after instantiating
or modifying.
sourcepub fn new(
address: DataAddress,
nrs_name: Option<&str>,
type_tag: u64,
content_type: ContentType,
path: Option<&str>,
sub_names: Option<Vec<String>>,
query_string: Option<&str>,
fragment: Option<&str>,
content_version: Option<VersionHash>
) -> Result<Self, Error>
pub fn new( address: DataAddress, nrs_name: Option<&str>, type_tag: u64, content_type: ContentType, path: Option<&str>, sub_names: Option<Vec<String>>, query_string: Option<&str>, fragment: Option<&str>, content_version: Option<VersionHash> ) -> Result<Self, Error>
Instantiates a new SafeUrl
Performs some basic validation checks, however it is possible to create invalid urls using this method.
Arguments
xor_name
-XorName
hashnrs_name
- complete nrs name, or None for xorurltype_tag
- type tagdata_type
-DataType
content_type
-ContentType
path
- must already be percent-encoded if Some. leading ‘/’ optional.xorurl_sub_names
-sub_names
. ignored ifnrs_name
is present.query_string
- must already be percent-encoded, without ? separatorfragment
- url fragment, without # separatorcontent_version
- overrides value of “?v” in query-string if not None.
sourcepub fn is_media_type_supported(media_type: &str) -> bool
pub fn is_media_type_supported(media_type: &str) -> bool
A non-member utility function to check if a media-type is currently supported by XOR-URL encoding
sourcepub fn from_nrsurl(nrsurl: &str) -> Result<Self, Error>
pub fn from_nrsurl(nrsurl: &str) -> Result<Self, Error>
sourcepub fn from_xorurl(xorurl: &str) -> Result<Self, Error>
pub fn from_xorurl(xorurl: &str) -> Result<Self, Error>
pub fn from_safekey(xor_name: XorName) -> Result<Self, Error>
pub fn from_bytes( address: XorName, content_type: ContentType ) -> Result<Self, Error>
pub fn from_register( xor_name: XorName, type_tag: u64, content_type: ContentType ) -> Result<Self, Error>
sourcepub fn encoding_version(&self) -> u64
pub fn encoding_version(&self) -> u64
returns encoding version of xorurl
sourcepub fn content_type(&self) -> ContentType
pub fn content_type(&self) -> ContentType
returns SAFE content type
sourcepub fn set_content_type(
&mut self,
content_type: ContentType
) -> Result<(), Error>
pub fn set_content_type( &mut self, content_type: ContentType ) -> Result<(), Error>
sets the SAFE content type
sourcepub fn address(&self) -> DataAddress
pub fn address(&self) -> DataAddress
returns address
sourcepub fn xorurl_public_name(&self) -> String
pub fn xorurl_public_name(&self) -> String
returns public_name
portion of xorurl using the
default xorurl encoding.
public_name
means sub_names
+ top_name
useful for retrieving xorurl name associated with an nrsurl.
For a different encoding, see name_to_base
()
sourcepub fn public_name(&self) -> &str
pub fn public_name(&self) -> &str
The public_name
in url. Either nrs_name
or xor_name
.
eg a.b.name –> a.b.name
sourcepub fn sub_names_vec(&self) -> &[String]
pub fn sub_names_vec(&self) -> &[String]
returns sub_names
in an array slice
eg: a.b.name –> &[“a”, “b”]
sourcepub fn set_sub_names(&mut self, sub_names: &str) -> Result<(), Error>
pub fn set_sub_names(&mut self, sub_names: &str) -> Result<(), Error>
sets sub_names
portion of URL
sourcepub fn path_decoded(&self) -> Result<String, Error>
pub fn path_decoded(&self) -> Result<String, Error>
returns path portion of URL, percent decoded
sourcepub fn set_path(&mut self, path: &str)
pub fn set_path(&mut self, path: &str)
sets path portion of URL
input string must not be percent-encoded. The encoding is done internally.
leading slash is automatically added if necessary.
sourcepub fn content_version(&self) -> Option<VersionHash>
pub fn content_version(&self) -> Option<VersionHash>
gets content version
This is a shortcut method for getting the “?v=” query param.
sourcepub fn set_content_version(&mut self, version: Option<VersionHash>)
pub fn set_content_version(&mut self, version: Option<VersionHash>)
sets content version
This is a shortcut method for setting the “?v=” query param.
Arguments
version
- u64 representing value of?v=<val>
sourcepub fn set_query_key(
&mut self,
key: &str,
val: Option<&str>
) -> Result<(), Error>
pub fn set_query_key( &mut self, key: &str, val: Option<&str> ) -> Result<(), Error>
sets or unsets a key/val pair in query string.
if val is Some, then key=val will be set in query string. If there is more than one instance of key in query string, there will be only one after this call. If val is None, then the key will be removed from query string.
To set key without any value, pass Some<“”> as the val.
val
should not be percent-encoded. That is done internally.
Arguments
key
- name of url query string varval
- an option representing the value, or none.
sourcepub fn set_query_string(&mut self, query: &str) -> Result<(), Error>
pub fn set_query_string(&mut self, query: &str) -> Result<(), Error>
sets query string.
If the query string contains ?v=<version>
then it
will take effect as if set_content_version
() had been
called.
Arguments
query
- percent-encoded key/val pairs.
sourcepub fn query_string(&self) -> &str
pub fn query_string(&self) -> &str
Retrieves query string
This contains the percent-encoded key/value pairs as seen in a url.
sourcepub fn query_string_with_separator(&self) -> String
pub fn query_string_with_separator(&self) -> String
Retrieves query string, with ? separator if non-empty.
sourcepub fn query_pairs(&self) -> Vec<(String, String)>
pub fn query_pairs(&self) -> Vec<(String, String)>
Retrieves all query pairs, percent-decoded.
sourcepub fn query_key(&self, key: &str) -> Vec<String>
pub fn query_key(&self, key: &str) -> Vec<String>
Queries a key from the query string.
Can return 0, 1, or many values because a given key may exist 0, 1, or many times in a URL query-string.
sourcepub fn query_key_last(&self, key: &str) -> Option<String>
pub fn query_key_last(&self, key: &str) -> Option<String>
returns the last matching key from a query string.
eg in safe://name?color=red&age=5&color=green&color=blue blue would be returned when key is “color”.
sourcepub fn query_key_first(&self, key: &str) -> Option<String>
pub fn query_key_first(&self, key: &str) -> Option<String>
returns the first matching key from a query string.
eg in safe://name?color=red&age=5&color=green&color=blue red would be returned when key is “color”.
sourcepub fn set_fragment(&mut self, fragment: String)
pub fn set_fragment(&mut self, fragment: String)
sets url fragment
sourcepub fn fragment_with_separator(&self) -> String
pub fn fragment_with_separator(&self) -> String
Retrieves url fragment, with # separator if non-empty.
sourcepub fn url_type(&self) -> &UrlType
pub fn url_type(&self) -> &UrlType
returns type of this url.
for type of the linked content, see
::content_type
()
sourcepub fn to_xorurl_string(&self) -> String
pub fn to_xorurl_string(&self) -> String
serializes the URL to an XorUrl
string.
This function may be called on an NrsUrl
and
the corresponding XorUrl
will be returned.
sourcepub fn to_nrsurl_string(&self) -> Option<String>
pub fn to_nrsurl_string(&self) -> Option<String>
serializes the URL to an NrsUrl
string.
This function returns None when is_nrsurl
() is false.
sourcepub fn name_to_base(&self, base: XorUrlBase, include_subnames: bool) -> String
pub fn name_to_base(&self, base: XorUrlBase, include_subnames: bool) -> String
serializes name portion of xorurl using a particular base encoding.
sourcepub fn url_percent_decode(s: &str) -> Result<String, Error>
pub fn url_percent_decode(s: &str) -> Result<String, Error>
Utility function to perform url percent decoding.
sourcepub fn url_percent_encode(s: &str) -> String
pub fn url_percent_encode(s: &str) -> String
Utility function to perform url percent encoding.
sourcepub fn validate(&self) -> Result<(), Error>
pub fn validate(&self) -> Result<(), Error>
Validates that a SafeUrl
instance can be parsed correctly.
SafeUrl::from_url
() performs rigorous validation,
however setters and new() do not enforce all the rules
This routine enables a caller to easily validate that the present instance passes all validation checks
sourcepub fn encode(&self, base: XorUrlBase) -> String
pub fn encode(&self, base: XorUrlBase) -> String
serializes entire xorurl using a particular base encoding.
Trait Implementations§
source§impl<'de> Deserialize<'de> for SafeUrl
impl<'de> Deserialize<'de> for SafeUrl
source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,
source§impl Ord for SafeUrl
impl Ord for SafeUrl
source§impl PartialEq<SafeUrl> for SafeUrl
impl PartialEq<SafeUrl> for SafeUrl
source§impl PartialOrd<SafeUrl> for SafeUrl
impl PartialOrd<SafeUrl> for SafeUrl
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl Eq for SafeUrl
impl StructuralEq for SafeUrl
impl StructuralPartialEq for SafeUrl
Auto Trait Implementations§
impl RefUnwindSafe for SafeUrl
impl Send for SafeUrl
impl Sync for SafeUrl
impl Unpin for SafeUrl
impl UnwindSafe for SafeUrl
Blanket Implementations§
§impl<T> Conv for T
impl<T> Conv for T
§impl<T> FmtForward for T
impl<T> FmtForward for T
§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where Self: Binary,
self
to use its Binary
implementation when Debug
-formatted.§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where Self: Display,
self
to use its Display
implementation when
Debug
-formatted.§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where Self: LowerExp,
self
to use its LowerExp
implementation when
Debug
-formatted.§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where Self: LowerHex,
self
to use its LowerHex
implementation when
Debug
-formatted.§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where Self: Octal,
self
to use its Octal
implementation when Debug
-formatted.§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where Self: Pointer,
self
to use its Pointer
implementation when
Debug
-formatted.§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where Self: UpperExp,
self
to use its UpperExp
implementation when
Debug
-formatted.§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where Self: UpperHex,
self
to use its UpperHex
implementation when
Debug
-formatted.§fn fmt_list(self) -> FmtList<Self>where
&'a Self: for<'a> IntoIterator,
fn fmt_list(self) -> FmtList<Self>where &'a Self: for<'a> IntoIterator,
source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere T: ?Sized,
§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere Self: Sized,
§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere R: 'a,
self
and passes that borrow into the pipe function. Read more§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere R: 'a,
self
and passes that borrow into the pipe function. Read more§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> Rwhere
Self: Borrow<B>,
B: 'a + ?Sized,
R: 'a,
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> Rwhere Self: Borrow<B>, B: 'a + ?Sized, R: 'a,
§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> Rwhere
Self: BorrowMut<B>,
B: 'a + ?Sized,
R: 'a,
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> Rwhere Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,
§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> Rwhere
Self: AsRef<U>,
U: 'a + ?Sized,
R: 'a,
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> Rwhere Self: AsRef<U>, U: 'a + ?Sized, R: 'a,
self
, then passes self.as_ref()
into the pipe function.§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> Rwhere
Self: AsMut<U>,
U: 'a + ?Sized,
R: 'a,
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> Rwhere Self: AsMut<U>, U: 'a + ?Sized, R: 'a,
self
, then passes self.as_mut()
into the pipe
function.§impl<T> Pointable for T
impl<T> Pointable for T
§impl<T> Tap for T
impl<T> Tap for T
§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Selfwhere
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,
Borrow<B>
of a value. Read more§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,
BorrowMut<B>
of a value. Read more§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Selfwhere
Self: AsRef<R>,
R: ?Sized,
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,
AsRef<R>
view of a value. Read more§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,
AsMut<R>
view of a value. Read more§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Selfwhere
Self: Deref<Target = T>,
T: ?Sized,
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Selfwhere Self: Deref<Target = T>, T: ?Sized,
Deref::Target
of a value. Read more§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere
Self: DerefMut<Target = T> + Deref,
T: ?Sized,
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere Self: DerefMut<Target = T> + Deref, T: ?Sized,
Deref::Target
of a value. Read more§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap()
only in debug builds, and is erased in release builds.§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut()
only in debug builds, and is erased in release
builds.§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Selfwhere
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,
.tap_borrow()
only in debug builds, and is erased in release
builds.§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,
.tap_borrow_mut()
only in debug builds, and is erased in release
builds.§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Selfwhere
Self: AsRef<R>,
R: ?Sized,
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,
.tap_ref()
only in debug builds, and is erased in release
builds.§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,
.tap_ref_mut()
only in debug builds, and is erased in release
builds.