12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576module juptune.core.ds.string;
struct String
{
/++ TEMPLATES ++/
/// Basic ctor that will copy the given char-based InputRange into the string.
template __ctor(RangeT){}
/// Quality of life constructor that is the rough equivalent of: Array!char buf; buf.put(values); return String.fromDestroyingArray(buf)
template __ctor(Values...){}
/// Concatenation operator.
template opBinary(string op)
{
/++ FUNCTIONS ++/
///
String opBinary(const char[] rhs);
///
String opBinary(String rhs);
///
String opBinary(String rhs);
}
/// Concatenation assignment operator.
template opOpAssign(string op)
{
/++ FUNCTIONS ++/
///
void opOpAssign(const char[] rhs);
///
void opOpAssign(String rhs);
///
void opOpAssign(String rhs);
}
/++ ALIASES ++/
///
alias __xdtor = __MARMOS_BUG__;
///
alias opDollar = __MARMOS_BUG__;
/++ FUNCTIONS ++/
/// A safer-ish way to access the underlying slice, by forcing it to go through a scoped delegate.
auto access(RetT)(RetT function(const char[]) accessor);
/// ditto.
auto access(RetT)(RetT function(const char[]) accessor);
/// A named constructor for String that will convert the given char-based Array into a string, and then destroy the array, effectively "moving" the array into a string.
String fromDestroyingArray(ArrayT)(ArrayT arr);
/// The length of the string.
ulong length();
/// Simple assignment operator that forwards to the appropriate ctor.
void opAssign(CtorParam)(CtorParam param);
///
String opAssign(String p);
/// Basic equality operator for common string types, including char[] , and String .
bool opEquals(const char[] rhs);
/// ditto.
bool opEquals(String rhs);
/// ditto.
bool opEquals(String rhs);
/// Simple [] operator to access the character at the given index.
char opIndex(const ulong index);
/// Provides an input range over the string's characters.
auto range();
/// Provides access to the raw slice of the string, which will always be on the heap.
const char[] slice();
/// Provides access to the raw slice of the string, which may be on the stack or heap, depending on if Small String Optimisation is in use.
const char[] sliceMaybeFromStack();
/// Hashes the contents of the string using MurmurHash3.
uint toHash();
}
An immutable string implemenetation with small string optimization, focused on making it safe and efficient to pass around a string by value by trading off the ability to mutate the string.
This struct is not** thread safe.
This struct will apply small string optimization (SSO) to store small strings in the struct itself, and will allocate memory for larger strings (or under specific conditions).
The SSO length will be ((void*).sizeof 3) - 1, which is 23 bytes on x86_64 for example.
This struct contains a ref counted payload, which is shared amongst copies of this struct. This is to make it very easy to pass the struct around without worrying about allocations.
This struct will never expose a mutable slice to the underlying memory, as it is assumed thet the string has already been fully constructed.
While this struct does provide a concat operation, it will always create a copy of the string, and thus is very inefficient for large strings. This is by design, use Array!charinstead.
To help avoid the need to provide direct access to the underlying slice (and risking escape), this struct attempts to provide enough operator overloads to make it easy to work with, for things like "String == char[]" operations.
Additionally there are 3 different ways to access the underlying slice, depending on use case and safety concerns: (`String.slice`, String.sliceMaybeFromStack, String.access), as well as a safer but more limited way via the String.rangefunction.
In the rare instances you need to pass the slice to a native C function, please note that the underlying memory is null terminated (but not subslices of the payload).
Not yet measured to any reasonable degree, however logically it should be much more efficient than the previous implementation which would do a full copy on every struct copy, and had gaping memory safety holes.
The assumption is that any operation self contained within the struct's code is @safe, and any operation that requires the underlying slice to be exposed is to be explicitly marked as @trusted by the caller.
This struct is only safe to move as long as there's no living slices to the string's SSO buffer.
| Name | Description |
|---|---|
| __xdtor | |
| opDollar |
| Name | Description |
|---|---|
| access |
A safer-ish way to access the underlying slice, by forcing it to go through a scoped delegate. |
| access |
ditto. |
| fromDestroyingArray |
A named constructor for |
| length |
The length of the string. |
| opAssign |
Simple assignment operator that forwards to the appropriate ctor. |
| opAssign | |
| opEquals |
Basic equality operator for common string types, including |
| opEquals |
ditto. |
| opEquals |
ditto. |
| opIndex |
Simple [] operator to access the character at the given index. |
| range |
Provides an input range over the string's characters. |
| slice |
Provides access to the raw slice of the string, which will always be on the heap. |
| sliceMaybeFromStack |
Provides access to the raw slice of the string, which may be on the stack or heap, depending on if Small String Optimisation is in use. |
| toHash |
Hashes the contents of the string using MurmurHash3. |
| Name | Description |
|---|---|
| __ctor |
Basic ctor that will copy the given char-based InputRange into the string. |
| __ctor |
Quality of life constructor that is the rough equivalent of: |
| opBinary |
Concatenation operator. |
| opOpAssign |
Concatenation assignment operator. |