String manipulation
Strings are a packed UTF-8 representation of text, stored as null terminated buffers of u8 bytes. Strings should be indexed in bytes, for efficiency, but UTF-8 unsafe operations should be avoided. For some heavy-duty uses, try extra::rope.
AnyLineIterator
- An iterator over the lines of a string, separated by either \\n
or (\\r\\n
).WordIterator
- An iterator over the words of a string, separated by an sequence of whitespaceCharRange
StrBytesIterator
- External iterator for a string's bytesStrBytesRevIterator
- External iterator for a string's bytes in reverse orderStrCharIterator
- External iterator for a string's charactersStrCharRevIterator
- External iterator for a string's characters in reverse orderStrCharSplitIterator
- An iterator over the substrings of a string, separated by sep
.StrMatchesIndexIterator
- An iterator over the start and end indicies of the matches of a substring within a larger stringStrStrSplitIterator
- An iterator over the substrings of a string separated by a given search stringCharEq
- Something that can be used to compare against a characterNullTerminatedStr
OwnedStr
Str
- Any string that can be represented as a sliceStrSlice
StrUtil
- A dummy trait to hold all the utility methods that we implement on strings.StrVector
of ToStr for ~str
of ToStr for &'self str where <'self>
of ToStr for @str
of StrVector for &'self [S] where <'self, S: Str>
of CharEq for char
of CharEq for &'self fn(char) -> bool where <'self>
of CharEq for extern "Rust" fn(char) -> bool
of CharEq for &'self [C] where <'self, C: CharEq>
of Iterator<&'self str> for StrCharSplitIterator<'self, Sep> where <'self, Sep: CharEq>
of Iterator<(uint, uint)> for StrMatchesIndexIterator<'self> where <'self>
of Iterator<&'self str> for StrStrSplitIterator<'self> where <'self>
of StrUtil for &'self str where <'self>
of Str for &'self str where <'self>
of Str for ~str where <'self>
of Str for @str where <'self>
of Container for &'self str where <'self>
of StrSlice<'self> for &'self str where <'self>
- Extension methods for stringsof NullTerminatedStr for ~str
of NullTerminatedStr for @str
of OwnedStr for ~str
of Clone for ~str
of Iterator<char> for StrCharIterator<'self> where <'self>
of Iterator<char> for StrCharRevIterator<'self> where <'self>
of Iterator<u8> for StrBytesIterator<'self> where <'self>
of Iterator<u8> for StrBytesRevIterator<'self> where <'self>
of Zero for &'self str where <'self>
of Zero for ~str
of Zero for @str
as_buf
- Work with the byte buffer and length of a slice.as_c_str
- Deprecatedcount_bytes
- Counts the number of bytes taken by the first n
chars in s
starting from start
.count_chars
- As char_len but for a slice of a stringeach_split_within
- Splits a string into substrings with possibly internal whitespace, * each of them at most lim
bytes longeq
- Bytewise string equalityeq_slice
- Bytewise slice equalityfrom_byte
- Convert a byte to a UTF-8 stringfrom_bytes
- Convert a vector of bytes to a new UTF-8 stringfrom_bytes_owned
- Consumes a vector of bytes to create a new utf-8 stringfrom_bytes_slice
- Converts a vector to a string slice without performing any allocations.from_bytes_with_null
- Convert a vector of bytes to a UTF-8 stringfrom_char
- Convert a char to a stringfrom_chars
- Convert a vector of chars to a stringfrom_utf16
- Allocates a new string from the utf-16 slice providedis_utf16
- Determines if a vector of u16
contains valid UTF-16is_utf8
- Determines if a vector of bytes contains valid UTF-8replace
- Replace all occurrences of one string with anotherto_owned
- Copy a slice into a new unique strutf16_chars
utf8_char_width
- Given a first byte, determine how many bytes are in this UTF-8 characterwith_capacity
- Allocates a new string with the specified capacitystr::not_utf8
str::raw
- Unsafe operationsstr::traits
AnyLineIterator
type AnyLineIterator<'self> = MapIterator<'self, &'self str, &'self str, StrCharSplitIterator<'self, char>>
An iterator over the lines of a string, separated by either \\n
or (\\r\\n
).
WordIterator
type WordIterator<'self> = FilterIterator<'self,
&'self str, StrCharSplitIterator<'self, extern "Rust" fn(char) -> bool>>
An iterator over the words of a string, separated by an sequence of whitespace
CharRange
pub struct CharRange {
ch: char,
next: uint,
}
StrBytesIterator
pub struct StrBytesIterator<'self> {
priv it: vec::VecIterator<'self, u8>,
}
External iterator for a string's bytes. Use with the std::iterator
module.
StrBytesRevIterator
pub struct StrBytesRevIterator<'self> {
priv it: vec::VecRevIterator<'self, u8>,
}
External iterator for a string's bytes in reverse order. Use with the std::iterator
module.
StrCharIterator
pub struct StrCharIterator<'self> {
priv index: uint,
priv string: &'self str,
}
External iterator for a string's characters. Use with the std::iterator
module.
StrCharRevIterator
pub struct StrCharRevIterator<'self> {
priv index: uint,
priv string: &'self str,
}
External iterator for a string's characters in reverse order. Use with the std::iterator
module.
StrCharSplitIterator
pub struct StrCharSplitIterator<'self, Sep> {
priv string: &'self str,
priv position: uint,
priv sep: Sep,
/// The number of splits remaining
priv count: uint,
/// Whether an empty string at the end is allowed
priv allow_trailing_empty: bool,
priv finished: bool,
priv only_ascii: bool,
}
An iterator over the substrings of a string, separated by sep
.
StrMatchesIndexIterator
pub struct StrMatchesIndexIterator<'self> {
priv haystack: &'self str,
priv needle: &'self str,
priv position: uint,
}
An iterator over the start and end indicies of the matches of a substring within a larger string
StrStrSplitIterator
pub struct StrStrSplitIterator<'self> {
priv it: StrMatchesIndexIterator<'self>,
priv last_end: uint,
priv finished: bool,
}
An iterator over the substrings of a string separated by a given search string
CharEq
Something that can be used to compare against a character
matches
fn matches(&self, char) -> bool
Determine if the splitter should split at the given character
only_ascii
fn only_ascii(&self) -> bool
Indicate if this is only concerned about ASCII characters, which can allow for a faster implementation.
NullTerminatedStr
as_bytes_with_null
fn as_bytes_with_null<'a>(&'a self) -> &'a [u8]
OwnedStr
push_str_no_overallocate
fn push_str_no_overallocate(&mut self, rhs: &str)
push_str
fn push_str(&mut self, rhs: &str)
push_char
fn push_char(&mut self, c: char)
pop_char
fn pop_char(&mut self) -> char
shift_char
fn shift_char(&mut self) -> char
unshift_char
fn unshift_char(&mut self, ch: char)
append
fn append(&self, rhs: &str) -> ~str
reserve
fn reserve(&mut self, n: uint)
reserve_at_least
fn reserve_at_least(&mut self, n: uint)
capacity
fn capacity(&self) -> uint
as_bytes_with_null_consume
fn as_bytes_with_null_consume(self) -> ~[u8]
Str
Any string that can be represented as a slice
as_slice
fn as_slice<'a>(&'a self) -> &'a str
Work with self
as a slice.
StrSlice
contains
fn contains<'a>(&self, needle: &'a str) -> bool
contains_char
fn contains_char(&self, needle: char) -> bool
iter
fn iter(&self) -> StrCharIterator<'self>
rev_iter
fn rev_iter(&self) -> StrCharRevIterator<'self>
bytes_iter
fn bytes_iter(&self) -> StrBytesIterator<'self>
bytes_rev_iter
fn bytes_rev_iter(&self) -> StrBytesRevIterator<'self>
split_iter
fn split_iter<Sep: CharEq>(&self, sep: Sep) ->
StrCharSplitIterator<'self, Sep>
splitn_iter
fn splitn_iter<Sep: CharEq>(&self, sep: Sep, count: uint) ->
StrCharSplitIterator<'self, Sep>
split_options_iter
fn split_options_iter<Sep: CharEq>(&self, sep: Sep, count: uint,
allow_trailing_empty: bool) ->
StrCharSplitIterator<'self, Sep>
matches_index_iter
fn matches_index_iter(&self, sep: &'self str) ->
StrMatchesIndexIterator<'self>
split_str_iter
fn split_str_iter(&self, &'self str) -> StrStrSplitIterator<'self>
line_iter
fn line_iter(&self) -> StrCharSplitIterator<'self, char>
any_line_iter
fn any_line_iter(&self) -> AnyLineIterator<'self>
word_iter
fn word_iter(&self) -> WordIterator<'self>
ends_with
fn ends_with(&self, needle: &str) -> bool
is_whitespace
fn is_whitespace(&self) -> bool
is_alphanumeric
fn is_alphanumeric(&self) -> bool
char_len
fn char_len(&self) -> uint
slice
fn slice(&self, begin: uint, end: uint) -> &'self str
slice_from
fn slice_from(&self, begin: uint) -> &'self str
slice_to
fn slice_to(&self, end: uint) -> &'self str
slice_chars
fn slice_chars(&self, begin: uint, end: uint) -> &'self str
starts_with
fn starts_with(&self, needle: &str) -> bool
escape_default
fn escape_default(&self) -> ~str
escape_unicode
fn escape_unicode(&self) -> ~str
trim
fn trim(&self) -> &'self str
trim_left
fn trim_left(&self) -> &'self str
trim_right
fn trim_right(&self) -> &'self str
trim_chars
fn trim_chars<C: CharEq>(&self, to_trim: &C) -> &'self str
trim_left_chars
fn trim_left_chars<C: CharEq>(&self, to_trim: &C) -> &'self str
trim_right_chars
fn trim_right_chars<C: CharEq>(&self, to_trim: &C) -> &'self str
replace
fn replace(&self, from: &str, to: &str) -> ~str
to_owned
fn to_owned(&self) -> ~str
to_managed
fn to_managed(&self) -> @str
to_utf16
fn to_utf16(&self) -> ~[u16]
is_char_boundary
fn is_char_boundary(&self, index: uint) -> bool
char_range_at
fn char_range_at(&self, start: uint) -> CharRange
char_at
fn char_at(&self, i: uint) -> char
char_range_at_reverse
fn char_range_at_reverse(&self, start: uint) -> CharRange
char_at_reverse
fn char_at_reverse(&self, i: uint) -> char
as_bytes
fn as_bytes(&self) -> &'self [u8]
find
fn find<C: CharEq>(&self, search: C) -> Option<uint>
rfind
fn rfind<C: CharEq>(&self, search: C) -> Option<uint>
find_str
fn find_str(&self, &str) -> Option<uint>
repeat
fn repeat(&self, nn: uint) -> ~str
slice_shift_char
fn slice_shift_char(&self) -> (char, &'self str)
map_chars
fn map_chars(&self, ff: &fn(char) -> char) -> ~str
lev_distance
fn lev_distance(&self, t: &str) -> uint
subslice_offset
fn subslice_offset(&self, inner: &str) -> uint
StrUtil
A dummy trait to hold all the utility methods that we implement on strings.
as_c_str
fn as_c_str<T>(self, f: &fn(*libc::c_char) -> T) -> T
Work with the byte buffer of a string as a null-terminated C string.
Allows for unsafe manipulation of strings, which is useful for foreign interop. This is similar to str::as_buf
, but guarantees null-termination. If the given slice is not already null-terminated, this function will allocate a temporary, copy the slice, null terminate it, and pass that instead.
let s = "PATH".as_c_str(|path| libc::getenv(path));
StrVector
concat
fn concat(&self) -> ~str
connect
fn connect(&self, sep: &str) -> ~str
ToStr
for ~str
to_str
fn to_str(&self) -> ~str
ToStr
for &'self str
where <'self>
to_str
fn to_str(&self) -> ~str
ToStr
for @str
to_str
fn to_str(&self) -> ~str
StrVector
for &'self [S]
where <'self, S: Str>
concat
fn concat(&self) -> ~str
Concatenate a vector of strings.
connect
fn connect(&self, sep: &str) -> ~str
Concatenate a vector of strings, placing a given separator between each.
CharEq
for char
matches
fn matches(&self, c: char) -> bool
only_ascii
fn only_ascii(&self) -> bool
CharEq
for &'self fn(char) -> bool
where <'self>
matches
fn matches(&self, c: char) -> bool
only_ascii
fn only_ascii(&self) -> bool
CharEq
for extern "Rust" fn(char) -> bool
matches
fn matches(&self, c: char) -> bool
only_ascii
fn only_ascii(&self) -> bool
CharEq
for &'self [C]
where <'self, C: CharEq>
matches
fn matches(&self, c: char) -> bool
only_ascii
fn only_ascii(&self) -> bool
Iterator<&'self str>
for StrCharSplitIterator<'self, Sep>
where <'self, Sep: CharEq>
next
fn next(&mut self) -> Option<&'self str>
Iterator<(uint, uint)>
for StrMatchesIndexIterator<'self>
where <'self>
next
fn next(&mut self) -> Option<(uint, uint)>
Iterator<&'self str>
for StrStrSplitIterator<'self>
where <'self>
next
fn next(&mut self) -> Option<&'self str>
StrUtil
for &'self str
where <'self>
as_c_str
fn as_c_str<T>(self, f: &fn(*libc::c_char) -> T) -> T
Str
for &'self str
where <'self>
as_slice
fn as_slice<'a>(&'a self) -> &'a str
Str
for ~str
where <'self>
as_slice
fn as_slice<'a>(&'a self) -> &'a str
Str
for @str
where <'self>
as_slice
fn as_slice<'a>(&'a self) -> &'a str
Container
for &'self str
where <'self>
len
fn len(&self) -> uint
is_empty
fn is_empty(&self) -> bool
StrSlice<'self>
for &'self str
where <'self>
Extension methods for strings
contains
fn contains<'a>(&self, needle: &'a str) -> bool
Returns true if one string contains another
contains_char
fn contains_char(&self, needle: char) -> bool
Returns true if a string contains a char.
iter
fn iter(&self) -> StrCharIterator<'self>
An iterator over the characters of self
. Note, this iterates over unicode code-points, not unicode graphemes.
let v: ~[char] = "abc åäö".iter().collect();
assert_eq!(v, ~['a', 'b', 'c', ' ', 'å', 'ä', 'ö']);
rev_iter
fn rev_iter(&self) -> StrCharRevIterator<'self>
An iterator over the characters of self
, in reverse order.
bytes_iter
fn bytes_iter(&self) -> StrBytesIterator<'self>
An iterator over the bytes of self
bytes_rev_iter
fn bytes_rev_iter(&self) -> StrBytesRevIterator<'self>
An iterator over the bytes of self
, in reverse order
split_iter
fn split_iter<Sep: CharEq>(&self, sep: Sep) ->
StrCharSplitIterator<'self, Sep>
An iterator over substrings of self
, separated by characters matched by sep
.
let v: ~[&str] = "Mary had a little lamb".split_iter(' ').collect();
assert_eq!(v, ~["Mary", "had", "a", "little", "lamb"]);
let v: ~[&str] = "abc1def2ghi".split_iter(|c: char| c.is_digit()).collect();
assert_eq!(v, ~["abc", "def", "ghi"]);
splitn_iter
fn splitn_iter<Sep: CharEq>(&self, sep: Sep, count: uint) ->
StrCharSplitIterator<'self, Sep>
An iterator over substrings of self
, separated by characters matched by sep
, restricted to splitting at most count
times.
split_options_iter
fn split_options_iter<Sep: CharEq>(&self, sep: Sep, count: uint,
allow_trailing_empty: bool) ->
StrCharSplitIterator<'self, Sep>
An iterator over substrings of self
, separated by characters matched by sep
, splitting at most count
times, and possibly not including the trailing empty substring, if it exists.
matches_index_iter
fn matches_index_iter(&self, sep: &'self str) ->
StrMatchesIndexIterator<'self>
An iterator over the start and end indices of each match of sep
within self
.
split_str_iter
fn split_str_iter(&self, sep: &'self str) -> StrStrSplitIterator<'self>
An iterator over the substrings of self
separated by sep
.
let v: ~[&str] = "abcXXXabcYYYabc".split_str_iter("abc").collect()
assert_eq!(v, ["", "XXX", "YYY", ""]);
line_iter
fn line_iter(&self) -> StrCharSplitIterator<'self, char>
An iterator over the lines of a string (subsequences separated by \\n
).
any_line_iter
fn any_line_iter(&self) -> AnyLineIterator<'self>
An iterator over the lines of a string, separated by either \\n
or (\\r\\n
).
word_iter
fn word_iter(&self) -> WordIterator<'self>
An iterator over the words of a string (subsequences separated by any sequence of whitespace).
is_whitespace
fn is_whitespace(&self) -> bool
Returns true if the string contains only whitespace
Whitespace characters are determined by char::is_whitespace
is_alphanumeric
fn is_alphanumeric(&self) -> bool
Returns true if the string contains only alphanumerics
Alphanumeric characters are determined by char::is_alphanumeric
char_len
fn char_len(&self) -> uint
Returns the number of characters that a string holds
slice
fn slice(&self, begin: uint, end: uint) -> &'self str
Returns a slice of the given string from the byte range [begin
..end
)
Fails when begin
and end
do not point to valid characters or beyond the last character of the string
slice_from
fn slice_from(&self, begin: uint) -> &'self str
Returns a slice of the string from begin
to its end.
Fails when begin
does not point to a valid character, or is out of bounds.
slice_to
fn slice_to(&self, end: uint) -> &'self str
Returns a slice of the string from the beginning to byte end
.
Fails when end
does not point to a valid character, or is out of bounds.
slice_chars
fn slice_chars(&self, begin: uint, end: uint) -> &'self str
Returns a slice of the string from the char range [begin
..end
).
Fails if begin
> end
or the either begin
or end
are beyond the last character of the string.
starts_with
fn starts_with<'a>(&self, needle: &'a str) -> bool
Returns true if needle
is a prefix of the string.
ends_with
fn ends_with(&self, needle: &str) -> bool
Returns true if needle
is a suffix of the string.
escape_default
fn escape_default(&self) -> ~str
Escape each char in s
with char::escape_default.
escape_unicode
fn escape_unicode(&self) -> ~str
Escape each char in s
with char::escape_unicode.
trim
fn trim(&self) -> &'self str
Returns a string with leading and trailing whitespace removed
trim_left
fn trim_left(&self) -> &'self str
Returns a string with leading whitespace removed
trim_right
fn trim_right(&self) -> &'self str
Returns a string with trailing whitespace removed
trim_chars
fn trim_chars<C: CharEq>(&self, to_trim: &C) -> &'self str
Returns a string with characters that match to_trim
removed.
assert_eq!("11foo1bar11".trim_chars(&'1'), "foo1bar")
assert_eq!("12foo1bar12".trim_chars(& &['1', '2']), "foo1bar")
assert_eq!("123foo1bar123".trim_chars(&|c: char| c.is_digit()), "foo1bar")
trim_left_chars
fn trim_left_chars<C: CharEq>(&self, to_trim: &C) -> &'self str
Returns a string with leading chars_to_trim
removed.
assert_eq!("11foo1bar11".trim_left_chars(&'1'), "foo1bar11")
assert_eq!("12foo1bar12".trim_left_chars(& &['1', '2']), "foo1bar12")
assert_eq!("123foo1bar123".trim_left_chars(&|c: char| c.is_digit()), "foo1bar123")
trim_right_chars
fn trim_right_chars<C: CharEq>(&self, to_trim: &C) -> &'self str
Returns a string with trailing chars_to_trim
removed.
assert_eq!("11foo1bar11".trim_right_chars(&'1'), "11foo1bar")
assert_eq!("12foo1bar12".trim_right_chars(& &['1', '2']), "12foo1bar")
assert_eq!("123foo1bar123".trim_right_chars(&|c: char| c.is_digit()), "123foo1bar")
replace
fn replace(&self, from: &str, to: &str) -> ~str
Replace all occurrences of one string with another
The original string with all occurances of from
replaced with to
to_owned
fn to_owned(&self) -> ~str
Copy a slice into a new unique str
to_managed
fn to_managed(&self) -> @str
to_utf16
fn to_utf16(&self) -> ~[u16]
Converts to a vector of u16
encoded as UTF-16.
is_char_boundary
fn is_char_boundary(&self, index: uint) -> bool
Returns false if the index points into the middle of a multi-byte character sequence.
char_range_at
fn char_range_at(&self, i: uint) -> CharRange
Pluck a character out of a string and return the index of the next character.
This function can be used to iterate over the unicode characters of a string.
let s = "中华Việt Nam";
let i = 0u;
while i < s.len() {
let CharRange {ch, next} = s.char_range_at(i);
std::io::println(fmt!("%u: %c",i,ch));
i = next;
}
0: 中
3: 华
6: V
7: i
8: ệ
11: t
12:
13: N
14: a
15: m
A record {ch: char, next: uint} containing the char value and the byte index of the next unicode character.
If i
is greater than or equal to the length of the string. If i
is not the index of the beginning of a valid UTF-8 character.
char_at
fn char_at(&self, i: uint) -> char
Plucks the character starting at the i
th byte of a string
char_range_at_reverse
fn char_range_at_reverse(&self, start: uint) -> CharRange
Given a byte position and a str, return the previous char and its position.
This function can be used to iterate over a unicode string in reverse.
Returns 0 for next index if called on start index 0.
char_at_reverse
fn char_at_reverse(&self, i: uint) -> char
Plucks the character ending at the i
th byte of a string
as_bytes
fn as_bytes(&self) -> &'self [u8]
Work with the byte buffer of a string as a byte slice.
The byte slice does not include the null terminator.
find
fn find<C: CharEq>(&self, search: C) -> Option<uint>
Returns the byte index of the first character of self
that matches search
Some
containing the byte index of the last matching character or None
if there is no match
rfind
fn rfind<C: CharEq>(&self, search: C) -> Option<uint>
Returns the byte index of the last character of self
that matches search
Some
containing the byte index of the last matching character or None
if there is no match
find_str
fn find_str(&self, needle: &str) -> Option<uint>
Returns the byte index of the first matching substring
needle
- The string to search forSome
containing the byte index of the first matching substring or None
if there is no match
repeat
fn repeat(&self, nn: uint) -> ~str
Given a string, make a new string with repeated copies of it.
slice_shift_char
fn slice_shift_char(&self) -> (char, &'self str)
Retrieves the first character from a string slice and returns it. This does not allocate a new string; instead, it returns a slice that point one character beyond the character that was shifted.
If the string does not contain any characters
map_chars
fn map_chars(&self, ff: &fn(char) -> char) -> ~str
Apply a function to each character.
lev_distance
fn lev_distance(&self, t: &str) -> uint
Levenshtein Distance between two strings.
subslice_offset
fn subslice_offset(&self, inner: &str) -> uint
Returns the byte offset of an inner slice relative to an enclosing outer slice.
Fails if inner
is not a direct slice contained within self.
let string = "a\\nb\\nc";
let mut lines = ~[];
for string.line_iter().advance |line| { lines.push(line) }
assert!(string.subslice_offset(lines[0]) == 0); // &"a"
assert!(string.subslice_offset(lines[1]) == 2); // &"b"
assert!(string.subslice_offset(lines[2]) == 4); // &"c"
NullTerminatedStr
for ~str
as_bytes_with_null
fn as_bytes_with_null<'a>(&'a self) -> &'a [u8]
Work with the byte buffer of a string as a byte slice.
The byte slice does include the null terminator.
NullTerminatedStr
for @str
as_bytes_with_null
fn as_bytes_with_null<'a>(&'a self) -> &'a [u8]
Work with the byte buffer of a string as a byte slice.
The byte slice does include the null terminator.
OwnedStr
for ~str
push_str_no_overallocate
fn push_str_no_overallocate(&mut self, rhs: &str)
Appends a string slice to the back of a string, without overallocating
push_str
fn push_str(&mut self, rhs: &str)
Appends a string slice to the back of a string
push_char
fn push_char(&mut self, c: char)
Appends a character to the back of a string
pop_char
fn pop_char(&mut self) -> char
Remove the final character from a string and return it
If the string does not contain any characters
shift_char
fn shift_char(&mut self) -> char
Remove the first character from a string and return it
If the string does not contain any characters
unshift_char
fn unshift_char(&mut self, ch: char)
Prepend a char to a string
append
fn append(&self, rhs: &str) -> ~str
Concatenate two strings together.
reserve
fn reserve(&mut self, n: uint)
Reserves capacity for exactly n
bytes in the given string, not including the null terminator.
Assuming single-byte characters, the resulting string will be large enough to hold a string of length n
. To account for the null terminator, the underlying buffer will have the size n
+ 1.
If the capacity for s
is already equal to or greater than the requested capacity, then no action is taken.
reserve_at_least
fn reserve_at_least(&mut self, n: uint)
Reserves capacity for at least n
bytes in the given string, not including the null terminator.
Assuming single-byte characters, the resulting string will be large enough to hold a string of length n
. To account for the null terminator, the underlying buffer will have the size n
+ 1.
This function will over-allocate in order to amortize the allocation costs in scenarios where the caller may need to repeatedly reserve additional space.
If the capacity for s
is already equal to or greater than the requested capacity, then no action is taken.
capacity
fn capacity(&self) -> uint
Returns the number of single-byte characters the string can hold without reallocating
as_bytes_with_null_consume
fn as_bytes_with_null_consume(self) -> ~[u8]
Convert to a vector of bytes. This does not allocate a new string, and includes the null terminator.
Clone
for ~str
clone
fn clone(&self) -> ~str
Iterator<char>
for StrCharIterator<'self>
where <'self>
next
fn next(&mut self) -> Option<char>
Iterator<char>
for StrCharRevIterator<'self>
where <'self>
next
fn next(&mut self) -> Option<char>
Iterator<u8>
for StrBytesIterator<'self>
where <'self>
next
fn next(&mut self) -> Option<u8>
Iterator<u8>
for StrBytesRevIterator<'self>
where <'self>
next
fn next(&mut self) -> Option<u8>
Zero
for &'self str
where <'self>
zero
fn zero() -> &'self str
is_zero
fn is_zero(&self) -> bool
Zero
for ~str
zero
fn zero() -> ~str
is_zero
fn is_zero(&self) -> bool
Zero
for @str
zero
fn zero() -> @str
is_zero
fn is_zero(&self) -> bool
as_buf
fn as_buf<T>(s: &str, f: &fn(*u8, uint) -> T) -> T
Work with the byte buffer and length of a slice.
The given length is one byte longer than the 'official' indexable length of the string. This is to permit probing the byte past the indexable area for a null byte, as is the case in slices pointing to full strings, or suffixes of them.
as_c_str
fn as_c_str<T>(s: &str, f: &fn(*libc::c_char) -> T) -> T
Deprecated. Use the as_c_str
method on strings instead.
count_bytes
fn count_bytes<'b>(s: &'b str, start: uint, n: uint) -> uint
Counts the number of bytes taken by the first n
chars in s
starting from start
.
count_chars
fn count_chars(s: &str, start: uint, end: uint) -> uint
As char_len but for a slice of a string
s
where to start counting in bytesThe number of Unicode characters in s
between the given indices.
each_split_within
fn each_split_within<'a>(ss: &'a str, lim: uint, it: &fn(&'a str) -> bool) ->
bool
Splits a string into substrings with possibly internal whitespace, * each of them at most lim
bytes long. The substrings have leading and trailing * whitespace removed, and are only cut at whitespace boundaries. * * #Failure: * * Fails during iteration if the string contains a non-whitespace * sequence longer than the limit.
eq
fn eq(a: &~str, b: &~str) -> bool
Bytewise string equality
eq_slice
fn eq_slice(a: &str, b: &str) -> bool
Bytewise slice equality
from_byte
fn from_byte(b: u8) -> ~str
Convert a byte to a UTF-8 string
Fails if invalid UTF-8
from_bytes
fn from_bytes(vv: &[u8]) -> ~str
Convert a vector of bytes to a new UTF-8 string
Raises the not_utf8
condition if invalid UTF-8
from_bytes_owned
fn from_bytes_owned(vv: ~[u8]) -> ~str
Consumes a vector of bytes to create a new utf-8 string
Raises the not_utf8
condition if invalid UTF-8
from_bytes_slice
fn from_bytes_slice<'a>(vector: &'a [u8]) -> &'a str
Converts a vector to a string slice without performing any allocations.
Once the slice has been validated as utf-8, it is transmuted in-place and returned as a '&str' instead of a '&[u8]'
Fails if invalid UTF-8
from_bytes_with_null
fn from_bytes_with_null<'a>(vv: &'a [u8]) -> &'a str
Convert a vector of bytes to a UTF-8 string. The vector needs to be one byte longer than the string, and end with a 0 byte.
Compared to from_bytes()
, this fn doesn't need to allocate a new owned str.
Fails if invalid UTF-8 Fails if not null terminated
from_char
fn from_char(ch: char) -> ~str
Convert a char to a string
from_chars
fn from_chars(chs: &[char]) -> ~str
Convert a vector of chars to a string
from_utf16
fn from_utf16(v: &[u16]) -> ~str
Allocates a new string from the utf-16 slice provided
is_utf16
fn is_utf16(v: &[u16]) -> bool
Determines if a vector of u16
contains valid UTF-16
is_utf8
fn is_utf8(v: &[u8]) -> bool
Determines if a vector of bytes contains valid UTF-8
replace
fn replace(s: &str, from: &str, to: &str) -> ~str
Replace all occurrences of one string with another
The original string with all occurances of from
replaced with to
to_owned
fn to_owned(s: &str) -> ~str
Copy a slice into a new unique str
utf16_chars
fn utf16_chars(v: &[u16], f: &fn(char))
Iterates over the utf-16 characters in the specified slice, yielding each decoded unicode character to the function provided.
utf8_char_width
fn utf8_char_width(b: u8) -> uint
Given a first byte, determine how many bytes are in this UTF-8 character
with_capacity
fn with_capacity(capacity: uint) -> ~str
Allocates a new string with the specified capacity. The string returned is the empty string, but has capacity for much more.