Struct AString 

pub struct AString<const CP: u32> { /* private fields */ }

An owned NUL-terminated ANSI string for code page CP.

A valid AString<CP> contains bytes accepted by Windows for code page CP, followed by exactly one terminating NUL in the retained string. Safe constructors reject interior NULs and invalid byte sequences. Unsafe constructors rely on the caller to preserve those invariants.

Implementations

impl<const CP: u32> AString<CP>

pub fn code_page(&self) -> u32

Gets the code page.

pub fn as_bytes(&self) -> &[u8]

Returns the bytes excluding the terminating NUL.

pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8]

Returns the mutable bytes excluding the terminating NUL.

Safety

The caller must preserve a string valid for code page CP without interior NULs.

pub fn as_bytes_with_nul(&self) -> &[u8]

Returns the bytes including the terminating NUL.

pub unsafe fn as_bytes_with_nul_mut(&mut self) -> &mut [u8]

Returns the mutable bytes including the terminating NUL.

Safety

The caller must preserve a valid, NUL-terminated string for code page CP without interior NULs.

pub fn len(&self) -> usize

Returns the length of bytes excluding the terminating NUL.

pub fn len_with_nul(&self) -> usize

Returns the length of bytes including the terminating NUL.

pub fn as_astr(&self) -> &AStr<CP>

Returns the string as a borrowed AStr.

pub fn as_mut_astr(&mut self) -> &mut AStr<CP>

Returns the string as a mutable borrowed AStr.

pub fn is_empty(&self) -> bool

Returns true if the string is empty.

pub fn new<T: Into<Vec<u8>>>(v: T) -> ConvertResult<Self>

Constructs an AString from bytes in code page CP.

The input must be valid for code page CP and must not contain interior NULs. If it is not NUL-terminated, a terminating NUL is appended.

pub fn from_vec_with_nul<T: Into<Vec<u8>>>(v: T) -> ConvertResult<Self>

Constructs an AString from NUL-terminated bytes in code page CP.

The input must be valid for code page CP, must end with a NUL byte, and must not contain interior NULs.

pub fn from_vec_until_nul<T: Into<Vec<u8>>>(v: T) -> ConvertResult<Self>

Constructs an AString from bytes in code page CP.

If the input contains a NUL, the string is truncated at the first NUL. If the input contains no NUL, a terminating NUL is appended.

pub unsafe fn from_vec_unchecked<T: Into<Vec<u8>>>(v: T) -> Self

Constructs an AString from bytes without validating the code page encoding.

Safety

v must contain data valid for code page CP up to the first NUL, without interior NULs in the retained string.

pub unsafe fn from_vec_with_nul_unchecked<T: Into<Vec<u8>>>(v: T) -> Self

Constructs an AString from NUL-terminated bytes without validation.

This function does not append a terminator. The supplied bytes must already contain the final NUL byte.

Safety

v must be valid for code page CP, NUL-terminated, and without interior NULs.

pub fn from_utf8(s: impl AsRef<str>) -> ConvertResult<Self>

Converts UTF-8 text to an AString using code page CP.

pub fn try_from_utf8_lossy(s: impl AsRef<str>) -> ConvertResult<Self>

Attempts to convert UTF-8 text to an AString using replacement when required by code page CP.

Embedded NUL characters are replaced before conversion. This can still fail if Windows rejects CP or the conversion parameters.

pub fn from_utf8_lossy(s: impl AsRef<str>) -> Self

Converts UTF-8 text to an AString using replacement when required by code page CP.

Panics

Panics if Windows rejects CP or if the underlying lossy conversion fails. Use try_from_utf8_lossy to handle that error explicitly.

pub unsafe fn clone_from_raw(ptr: *const u8) -> Self

Copies an AString from a raw NUL-terminated pointer.

This function scans for the first NUL with strlen, then delegates to clone_from_raw_s.

Safety

ptr must be non-null and readable through the first NUL. The scanned range must be contained in a single allocated object and must not exceed isize::MAX bytes. The pointed-to data before the first NUL must be valid for code page CP and must not contain interior NULs.

pub unsafe fn clone_from_raw_s(ptr: *const u8, len: usize) -> Self

Copies an AString from a raw pointer and explicit copied byte length without scanning for a terminator.

len is the number of bytes copied from ptr. This function does not read ptr.add(len). If the copied range does not already end in NUL, a terminating NUL is appended to the new AString.

Safety

ptr must be non-null and readable for len bytes. The copied range must be contained in a single allocated object and must not exceed isize::MAX bytes. The copied data must be valid for code page CP and must not contain NULs except possibly as the final copied byte.

pub fn into_bytes_with_nul(self) -> Vec<u8>

Consumes the string and returns the internal NUL-terminated buffer.

Methods from Deref<Target = AStr<CP>>

pub fn code_page(&self) -> u32

Gets the code page.

pub fn len(&self) -> usize

Returns the length of bytes excluding the terminating NUL.

pub fn len_with_nul(&self) -> usize

Returns the length of bytes including the terminating NUL.

pub fn as_ptr(&self) -> *const i8

Returns a raw i8 pointer to the first byte.

pub fn as_u8_ptr(&self) -> *const u8

Returns a raw u8 pointer to the first byte.

pub fn is_empty(&self) -> bool

Returns true if the string is empty.

pub fn as_bytes(&self) -> &[u8]

Returns the bytes excluding the terminating NUL.

pub fn as_bytes_with_nul(&self) -> &[u8]

Returns the bytes including the terminating NUL.

pub fn try_to_string(&self) -> ConvertResult<String>

Converts this borrowed ANSI string to a UTF-8 String.

This method returns a ConvertError if Windows rejects the code page or byte sequence. Values produced by unsafe constructors are not revalidated before conversion.

Trait Implementations

impl<const CP: u32> Add<&AStr<CP>> for AString<CP>

type Output = AString<CP>

The resulting type after applying the + operator.

fn add(self, rhs: &AStr<CP>) -> Self::Output

Performs the + operation.

impl<const CP: u32> AsRef<AStr<CP>> for AString<CP>

fn as_ref(&self) -> &AStr<CP>

Converts this type into a shared reference of the (usually inferred) input type.

impl<const CP: u32> Borrow<AStr<CP>> for AString<CP>

Available on crate feature std only.

fn borrow(&self) -> &AStr<CP>

Immutably borrows from an owned value.

impl<const CP: u32> Clone for AString<CP>

fn clone(&self) -> AString<CP>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const CP: u32> Debug for AString<CP>

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

Formats the value using the given formatter.

impl<const CP: u32> Deref for AString<CP>

type Target = AStr<CP>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<const CP: u32> Display for AString<CP>

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

Formats the value using the given formatter.

impl<const CP: u32> Eq for AString<CP>

impl<const CP: u32> From<&AStr<CP>> for AString<CP>

fn from(x: &AStr<CP>) -> Self

Converts to this type from the input type.

impl<const CP: u32> From<&AString<CP>> for DAString

fn from(value: &AString<CP>) -> Self

Converts to this type from the input type.

impl<const CP: u32> From<AString<CP>> for DAString

fn from(value: AString<CP>) -> Self

Converts to this type from the input type.

impl<const CP: u32> FromStr for AString<CP>

type Err = ConvertError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<const CP: u32> Hash for AString<CP>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<const CP: u32> Index<RangeFull> for AString<CP>

type Output = AStr<CP>

The returned type after indexing.

fn index(&self, _: RangeFull) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<const CP: u32> Ord for AString<CP>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<const CP: u32> PartialEq for AString<CP>

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

Equality operator ==.

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

Inequality operator !=.

impl<const CP: u32> PartialEq<&AStr<CP>> for AString<CP>

fn eq(&self, other: &&AStr<CP>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<const CP: u32> PartialEq<&AString<CP>> for AStr<CP>

Available on crate feature std only.

fn eq(&self, other: &&AString<CP>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<const CP: u32> PartialEq<AStr<CP>> for AString<CP>

fn eq(&self, other: &AStr<CP>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<const CP: u32> PartialEq<AString<CP>> for DAString

fn eq(&self, other: &AString<CP>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<const CP: u32> PartialEq<AString<CP>> for AStr<CP>

Available on crate feature std only.

fn eq(&self, other: &AString<CP>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<'a, const CP: u32> PartialEq<AString<CP>> for DAStr<'a>

Available on crate feature std only.

fn eq(&self, other: &AString<CP>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<'a, const CP: u32> PartialEq<DAStr<'a>> for AString<CP>

fn eq(&self, other: &DAStr<'a>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<const CP: u32> PartialEq<DAString> for AString<CP>

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

Equality operator ==.

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

Inequality operator !=.

impl<const CP: u32> PartialOrd for AString<CP>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const CP: u32> PartialOrd<&AStr<CP>> for AString<CP>

fn partial_cmp(&self, other: &&AStr<CP>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const CP: u32> PartialOrd<&AString<CP>> for AStr<CP>

Available on crate feature std only.

fn partial_cmp(&self, other: &&AString<CP>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const CP: u32> PartialOrd<AStr<CP>> for AString<CP>

fn partial_cmp(&self, other: &AStr<CP>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const CP: u32> PartialOrd<AString<CP>> for AStr<CP>

Available on crate feature std only.

fn partial_cmp(&self, other: &AString<CP>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const CP: u32> TryFrom<&AString<CP>> for WString

type Error = ConvertError

The type returned in the event of a conversion error.

fn try_from(x: &AString<CP>) -> Result<Self, Self::Error>

Performs the conversion.

impl<const CP: u32> TryFrom<&String> for AString<CP>

type Error = ConvertError

The type returned in the event of a conversion error.

fn try_from(x: &String) -> Result<Self, Self::Error>

Performs the conversion.

impl<const CP: u32> TryFrom<&WStr> for AString<CP>

type Error = ConvertError

The type returned in the event of a conversion error.

fn try_from(x: &WStr) -> Result<Self, Self::Error>

Performs the conversion.

impl<const CP: u32> TryFrom<&WString> for AString<CP>

type Error = ConvertError

The type returned in the event of a conversion error.

fn try_from(x: &WString) -> Result<Self, Self::Error>

Performs the conversion.

impl<const CP: u32> TryFrom<&str> for AString<CP>

type Error = ConvertError

The type returned in the event of a conversion error.

fn try_from(x: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl<const CP: u32> TryFrom<AString<CP>> for WString

type Error = ConvertError

The type returned in the event of a conversion error.

fn try_from(x: AString<CP>) -> Result<Self, Self::Error>

Performs the conversion.

impl<const CP: u32> TryFrom<AString<CP>> for String

type Error = ConvertError

The type returned in the event of a conversion error.

fn try_from(value: AString<CP>) -> Result<Self, Self::Error>

Performs the conversion.

impl<const CP: u32> TryFrom<String> for AString<CP>

type Error = ConvertError

The type returned in the event of a conversion error.

fn try_from(x: String) -> Result<Self, Self::Error>

Performs the conversion.

impl<const CP: u32> TryFrom<WString> for AString<CP>

type Error = ConvertError

The type returned in the event of a conversion error.

fn try_from(x: WString) -> Result<Self, Self::Error>

Performs the conversion.