Module `0x1::string`

The <code><a href="string.md#0x1_string">string</a></code> module defines the <code><a href="string.md#0x1_string_String">String</a></code> type which represents UTF8 encoded strings.

Struct String
Constants
Function utf8
Function try_utf8
Function bytes
Function into_bytes
Function is_empty
Function length
Function append
Function append_utf8
Function insert
Function sub_string
Function index_of
Function internal_check_utf8
Function internal_is_char_boundary
Function internal_sub_string
Function internal_index_of

<pre><code>use <a href="option.md#0x1_option">0x1::option</a>; use <a href="vector.md#0x1_vector">0x1::vector</a>; </code></pre>

Struct `String`

A <code><a href="string.md#0x1_string_String">String</a></code> holds a sequence of bytes which is guaranteed to be in utf8 format.

<pre><code>struct <a href="string.md#0x1_string_String">String</a> has copy, drop, store </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>bytes: <a href="vector.md#0x1_vector">vector</a><u8></code> </dt> <dd> </dd> </dl> </details>

Constants

Index out of range.

<pre><code>const <a href="string.md#0x1_string_EINVALID_INDEX">EINVALID_INDEX</a>: u64 = 2; </code></pre>

An invalid UTF8 encoding.

<pre><code>const <a href="string.md#0x1_string_EINVALID_UTF8">EINVALID_UTF8</a>: u64 = 1; </code></pre>

Function `utf8`

Creates a new string from a sequence of bytes. Aborts if the bytes do not represent valid utf8.

<pre><code>public fun <a href="string.md#0x1_string_utf8">utf8</a>(bytes: <a href="vector.md#0x1_vector">vector</a><u8>): <a href="string.md#0x1_string_String">string::String</a> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_utf8">utf8</a>(bytes: <a href="vector.md#0x1_vector">vector</a><u8>): <a href="string.md#0x1_string_String">String</a> { assert!(<a href="string.md#0x1_string_internal_check_utf8">internal_check_utf8</a>(&bytes), <a href="string.md#0x1_string_EINVALID_UTF8">EINVALID_UTF8</a>); <a href="string.md#0x1_string_String">String</a>{bytes} } </code></pre> </details>

Function `try_utf8`

Tries to create a new string from a sequence of bytes.

<pre><code>public fun <a href="string.md#0x1_string_try_utf8">try_utf8</a>(bytes: <a href="vector.md#0x1_vector">vector</a><u8>): <a href="option.md#0x1_option_Option">option::Option</a><<a href="string.md#0x1_string_String">string::String</a>> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_try_utf8">try_utf8</a>(bytes: <a href="vector.md#0x1_vector">vector</a><u8>): Option<<a href="string.md#0x1_string_String">String</a>> { if (<a href="string.md#0x1_string_internal_check_utf8">internal_check_utf8</a>(&bytes)) { <a href="option.md#0x1_option_some">option::some</a>(<a href="string.md#0x1_string_String">String</a>{bytes}) } else { <a href="option.md#0x1_option_none">option::none</a>() } } </code></pre> </details>

Function `bytes`

Returns a reference to the underlying byte vector.

<pre><code>public fun <a href="string.md#0x1_string_bytes">bytes</a>(s: &<a href="string.md#0x1_string_String">string::String</a>): &<a href="vector.md#0x1_vector">vector</a><u8> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_bytes">bytes</a>(s: &<a href="string.md#0x1_string_String">String</a>): &<a href="vector.md#0x1_vector">vector</a><u8> { &s.bytes } </code></pre> </details>

Function `into_bytes`

Returns the underlying byte vector.

<pre><code>public fun <a href="string.md#0x1_string_into_bytes">into_bytes</a>(s: <a href="string.md#0x1_string_String">string::String</a>): <a href="vector.md#0x1_vector">vector</a><u8> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_into_bytes">into_bytes</a>(s: <a href="string.md#0x1_string_String">String</a>): <a href="vector.md#0x1_vector">vector</a><u8> { let <a href="string.md#0x1_string_String">String</a> { bytes } = s; bytes } </code></pre> </details>

Function `is_empty`

Checks whether this string is empty.

<pre><code>public fun <a href="string.md#0x1_string_is_empty">is_empty</a>(s: &<a href="string.md#0x1_string_String">string::String</a>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_is_empty">is_empty</a>(s: &<a href="string.md#0x1_string_String">String</a>): bool { <a href="vector.md#0x1_vector_is_empty">vector::is_empty</a>(&s.bytes) } </code></pre> </details>

Function `length`

Returns the length of this string, in bytes.

<pre><code>public fun <a href="string.md#0x1_string_length">length</a>(s: &<a href="string.md#0x1_string_String">string::String</a>): u64 </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_length">length</a>(s: &<a href="string.md#0x1_string_String">String</a>): u64 { <a href="vector.md#0x1_vector_length">vector::length</a>(&s.bytes) } </code></pre> </details>

Function `append`

Appends a string.

<pre><code>public fun <a href="string.md#0x1_string_append">append</a>(s: &mut <a href="string.md#0x1_string_String">string::String</a>, r: <a href="string.md#0x1_string_String">string::String</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_append">append</a>(s: &mut <a href="string.md#0x1_string_String">String</a>, r: <a href="string.md#0x1_string_String">String</a>) { <a href="vector.md#0x1_vector_append">vector::append</a>(&mut s.bytes, r.bytes) } </code></pre> </details>

Function `append_utf8`

Appends bytes which must be in valid utf8 format.

<pre><code>public fun <a href="string.md#0x1_string_append_utf8">append_utf8</a>(s: &mut <a href="string.md#0x1_string_String">string::String</a>, bytes: <a href="vector.md#0x1_vector">vector</a><u8>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_append_utf8">append_utf8</a>(s: &mut <a href="string.md#0x1_string_String">String</a>, bytes: <a href="vector.md#0x1_vector">vector</a><u8>) { <a href="string.md#0x1_string_append">append</a>(s, <a href="string.md#0x1_string_utf8">utf8</a>(bytes)) } </code></pre> </details>

Function `insert`

Insert the other string at the byte index in given string. The index must be at a valid utf8 char boundary.

<pre><code>public fun <a href="string.md#0x1_string_insert">insert</a>(s: &mut <a href="string.md#0x1_string_String">string::String</a>, at: u64, o: <a href="string.md#0x1_string_String">string::String</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_insert">insert</a>(s: &mut <a href="string.md#0x1_string_String">String</a>, at: u64, o: <a href="string.md#0x1_string_String">String</a>) { let bytes = &s.bytes; assert!(at <= <a href="vector.md#0x1_vector_length">vector::length</a>(bytes) && <a href="string.md#0x1_string_internal_is_char_boundary">internal_is_char_boundary</a>(bytes, at), <a href="string.md#0x1_string_EINVALID_INDEX">EINVALID_INDEX</a>); let l = <a href="string.md#0x1_string_length">length</a>(s); let front = <a href="string.md#0x1_string_sub_string">sub_string</a>(s, 0, at); let end = <a href="string.md#0x1_string_sub_string">sub_string</a>(s, at, l); <a href="string.md#0x1_string_append">append</a>(&mut front, o); <a href="string.md#0x1_string_append">append</a>(&mut front, end); *s = front; } </code></pre> </details>

Function `sub_string`

Returns a sub-string using the given byte indices, where <code>i</code> is the first byte position and <code>j</code> is the start of the first byte not included (or the length of the string). The indices must be at valid utf8 char boundaries, guaranteeing that the result is valid utf8.

<pre><code>public fun <a href="string.md#0x1_string_sub_string">sub_string</a>(s: &<a href="string.md#0x1_string_String">string::String</a>, i: u64, j: u64): <a href="string.md#0x1_string_String">string::String</a> </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_sub_string">sub_string</a>(s: &<a href="string.md#0x1_string_String">String</a>, i: u64, j: u64): <a href="string.md#0x1_string_String">String</a> { let bytes = &s.bytes; let l = <a href="vector.md#0x1_vector_length">vector::length</a>(bytes); assert!( j <= l && i <= j && <a href="string.md#0x1_string_internal_is_char_boundary">internal_is_char_boundary</a>(bytes, i) && <a href="string.md#0x1_string_internal_is_char_boundary">internal_is_char_boundary</a>(bytes, j), <a href="string.md#0x1_string_EINVALID_INDEX">EINVALID_INDEX</a> ); <a href="string.md#0x1_string_String">String</a>{bytes: <a href="string.md#0x1_string_internal_sub_string">internal_sub_string</a>(bytes, i, j)} } </code></pre> </details>

Function `index_of`

Computes the index of the first occurrence of a string. Returns <code><a href="string.md#0x1_string_length">length</a>(s)</code> if no occurrence found.

<pre><code>public fun <a href="string.md#0x1_string_index_of">index_of</a>(s: &<a href="string.md#0x1_string_String">string::String</a>, r: &<a href="string.md#0x1_string_String">string::String</a>): u64 </code></pre> <details> <summary>Implementation</summary> <pre><code>public fun <a href="string.md#0x1_string_index_of">index_of</a>(s: &<a href="string.md#0x1_string_String">String</a>, r: &<a href="string.md#0x1_string_String">String</a>): u64 { <a href="string.md#0x1_string_internal_index_of">internal_index_of</a>(&s.bytes, &r.bytes) } </code></pre> </details>

Function `internal_check_utf8`

<pre><code>fun <a href="string.md#0x1_string_internal_check_utf8">internal_check_utf8</a>(v: &<a href="vector.md#0x1_vector">vector</a><u8>): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>native fun <a href="string.md#0x1_string_internal_check_utf8">internal_check_utf8</a>(v: &<a href="vector.md#0x1_vector">vector</a><u8>): bool; </code></pre> </details>

Function `internal_is_char_boundary`

<pre><code>fun <a href="string.md#0x1_string_internal_is_char_boundary">internal_is_char_boundary</a>(v: &<a href="vector.md#0x1_vector">vector</a><u8>, i: u64): bool </code></pre> <details> <summary>Implementation</summary> <pre><code>native fun <a href="string.md#0x1_string_internal_is_char_boundary">internal_is_char_boundary</a>(v: &<a href="vector.md#0x1_vector">vector</a><u8>, i: u64): bool; </code></pre> </details>

Function `internal_sub_string`

<pre><code>fun <a href="string.md#0x1_string_internal_sub_string">internal_sub_string</a>(v: &<a href="vector.md#0x1_vector">vector</a><u8>, i: u64, j: u64): <a href="vector.md#0x1_vector">vector</a><u8> </code></pre> <details> <summary>Implementation</summary> <pre><code>native fun <a href="string.md#0x1_string_internal_sub_string">internal_sub_string</a>(v: &<a href="vector.md#0x1_vector">vector</a><u8>, i: u64, j: u64): <a href="vector.md#0x1_vector">vector</a><u8>; </code></pre> </details>

Function `internal_index_of`

<pre><code>fun <a href="string.md#0x1_string_internal_index_of">internal_index_of</a>(v: &<a href="vector.md#0x1_vector">vector</a><u8>, r: &<a href="vector.md#0x1_vector">vector</a><u8>): u64 </code></pre> <details> <summary>Implementation</summary> <pre><code>native fun <a href="string.md#0x1_string_internal_index_of">internal_index_of</a>(v: &<a href="vector.md#0x1_vector">vector</a><u8>, r: &<a href="vector.md#0x1_vector">vector</a><u8>): u64; </code></pre> </details>

Module `0x1::string`

Module 0x1::string

Struct String

Constants

Function utf8

Function try_utf8

Function bytes

Function into_bytes

Function is_empty

Function length

Function append

Function append_utf8

Function insert

Function sub_string

Function index_of

Function internal_check_utf8

Function internal_is_char_boundary

Function internal_sub_string

Function internal_index_of

Module `0x1::string`

Struct `String`

Function `utf8`

Function `try_utf8`

Function `bytes`

Function `into_bytes`

Function `is_empty`

Function `length`

Function `append`

Function `append_utf8`

Function `insert`

Function `sub_string`

Function `index_of`

Function `internal_check_utf8`

Function `internal_is_char_boundary`

Function `internal_sub_string`

Function `internal_index_of`