Struct sn_url::SafeUrl

pub struct SafeUrl { /* fields omitted */ }

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

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.

pub fn new(
    xor_name: XorName,
    nrs_name: Option<&str>,
    type_tag: u64,
    data_type: SafeDataType,
    content_type: SafeContentType,
    path: Option<&str>,
    sub_names: Option<Vec<String>>,
    query_string: Option<&str>,
    fragment: Option<&str>,
    content_version: Option<u64>
) -> Result<Self>

Instantiates a new SafeUrl

Performs some basic validation checks, however it is possible to create invalid urls using this method.

Arguments

• xor_name - XorName hash
• nrs_name - complete nrs name, or None for xorurl
• type_tag - type tag
• data_type - SafeDataType
• content_type - SafeContentType
• path - must already be percent-encoded if Some. leading ‘/’ optional.
• xorurl_sub_names - sub_names. ignored if nrs_name is present.
• query_string - must already be percent-encoded, without ? separator
• fragment - url fragment, without # separator
• content_version - overrides value of “?v” in query-string if not None.

pub fn is_media_type_supported(media_type: &str) -> bool

pub fn from_url(url: &str) -> Result<Self>

Parses a safe url into SafeUrl

Arguments

• url - either nrsurl or xorurl

pub fn from_nrsurl(nrsurl: &str) -> Result<Self>

Parses an NRS Url into SafeUrl

Arguments

• nrsurl - an nrsurl.

pub fn from_xorurl(xorurl: &str) -> Result<Self>

Parses a XorUrl into SafeUrl

Arguments

• xorurl - an xorurl.

pub fn scheme(&self) -> &str

The url scheme. Only ‘safe’ scheme is presently supported.

pub fn encoding_version(&self) -> u64

returns encoding version of xorurl

pub fn data_type(&self) -> SafeDataType

returns SAFE data type

pub fn content_type(&self) -> SafeContentType

returns SAFE content type

pub fn set_content_type(&mut self, content_type: SafeContentType) -> Result<()>

sets the SAFE content type

pub fn xorname(&self) -> XorName

returns XorName

pub fn register_address(&self) -> Result<Address>

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()

pub fn public_name(&self) -> &str

The public_name in url. Either nrs_name or xor_name.

eg a.b.name –> a.b.name

pub fn top_name(&self) -> &str

returns top name of name field.

eg: a.b.name –> name

pub fn sub_names(&self) -> &str

returns sub_names

eg: a.b.name –> a.b

pub fn sub_names_vec(&self) -> &[String]

returns sub_names in an array slice

eg: a.b.name –> &[“a”, “b”]

pub fn set_sub_names(&mut self, sub_names: &str) -> Result<()>

sets sub_names portion of URL

pub fn type_tag(&self) -> u64

returns XorUrl type tag

pub fn path(&self) -> &str

returns path portion of URL, percent encoded (unmodified).

pub fn path_decoded(&self) -> Result<String>

returns path portion of URL, percent decoded

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.

pub fn content_version(&self) -> Option<u64>

gets content version

This is a shortcut method for getting the “?v=” query param.

pub fn set_content_version(&mut self, version: Option<u64>)

sets content version

This is a shortcut method for setting the “?v=” query param.

Arguments

• version - u64 representing value of ?v=

pub fn set_query_key(&mut self, key: &str, val: Option<&str>) -> Result<()>

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 var
• val - an option representing the value, or none.

pub fn set_query_string(&mut self, query: &str) -> Result<()>

sets query string.

If the query string contains ?v= then it will take effect as if set_content_version() had been called.

Arguments

• query - percent-encoded key/val pairs.

pub fn query_string(&self) -> &str

Retrieves query string

This contains the percent-encoded key/value pairs as seen in a url.

pub fn query_string_with_separator(&self) -> String

Retrieves query string, with ? separator if non-empty.

pub fn query_pairs(&self) -> Vec<(String, String)>

Retrieves all query pairs, percent-decoded.

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.

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”.

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”.

pub fn set_fragment(&mut self, fragment: String)

sets url fragment

pub fn fragment(&self) -> &str

Retrieves url fragment, without # separator

pub fn fragment_with_separator(&self) -> String

Retrieves url fragment, with # separator if non-empty.

pub fn is_nrsurl(&self) -> bool

returns true if an NrsUrl, false if an XorUrl

pub fn is_xorurl(&self) -> bool

returns true if an XorUrl, false if an NrsUrl

pub fn safeurl_type(&self) -> &SafeUrlType

returns type of this SafeUrl.

for type of the linked content, see ::content_type()

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.

pub fn to_nrsurl_string(&self) -> Option<String>

serializes the URL to an NrsUrl string.

This function returns None when is_nrsurl() is false.

pub fn to_base(&self, base: XorUrlBase) -> String

serializes entire xorurl using a particular base encoding.

pub fn name_to_base(&self, base: XorUrlBase, include_subnames: bool) -> String

serializes name portion of xorurl using a particular base encoding.

pub fn url_percent_decode(s: &str) -> Result<String>

Utility function to perform url percent decoding.

pub fn url_percent_encode(s: &str) -> String

Utility function to perform url percent encoding.

pub fn validate(&self) -> Result<()>

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

pub fn encode(
    xor_name: XorName,
    nrs_name: Option<&str>,
    type_tag: u64,
    data_type: SafeDataType,
    content_type: SafeContentType,
    path: Option<&str>,
    sub_names: Option<Vec<String>>,
    query_string: Option<&str>,
    fragment: Option<&str>,
    content_version: Option<u64>,
    base: XorUrlBase
) -> Result<String>

pub fn encode_safekey(xor_name: XorName, base: XorUrlBase) -> Result<String>

pub fn encode_blob(
    xor_name: XorName,
    content_type: SafeContentType,
    base: XorUrlBase
) -> Result<String>

pub fn encode_mutable_data(
    xor_name: XorName,
    type_tag: u64,
    content_type: SafeContentType,
    base: XorUrlBase
) -> Result<String>

pub fn encode_sequence_data(
    xor_name: XorName,
    type_tag: u64,
    content_type: SafeContentType,
    base: XorUrlBase,
    is_private: bool
) -> Result<String>

pub fn encode_register(
    xor_name: XorName,
    type_tag: u64,
    content_type: SafeContentType,
    base: XorUrlBase,
    is_private: bool
) -> Result<String>

Trait Implementations

impl Clone for SafeUrl

fn clone(&self) -> SafeUrl

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SafeUrl

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SafeUrl

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl Display for SafeUrl

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

serializes the URL to a string.

an NrsUrl will be serialized in NrsUrl form. an XorUrl will be serialized in XorUrl form.

See also:

• ::to_xorurl_string()
• ::to_nrs_url_string()

impl PartialEq<SafeUrl> for SafeUrl

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl Serialize for SafeUrl

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

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SafeUrl