Crate widestring [−] [src]
A wide string FFI library for converting to and from Windows Wide "Unicode" strings.
This crate provides two types of wide strings: WideString
and WideCString
. They differ
in the guaruntees they provide. For WideString
, no guaruntees are made about the underlying
string data; it is simply a sequence of UTF-16 values, which may be ill-formed or contain nul
values. WideCString
on the other hand is aware of nul values and is guarunteed to be
terminated with a nul value (unless unchecked methods are used to construct the WideCString
).
Because WideCString
is a C-style, nul-terminated string, it will have no interior nul values.
A WideCString
may still have ill-formed UTF-16 values.
Use WideString
when you simply need to pass-thru values, or when you know or don't care if
you're not dealing with a nul-terminated string, such as when string lengths are provided and
you are only reading strings from FFI, not passing them into FFI.
Use WideCString
when you must properly handle nul values, and must deal with nul-terminated
C-style wide strings, such as if you must pass string values into FFI functions.
While these types are roughly based on the types in std::os
, they are not an identical wide
version of OsString
and CString
, but do fill a similar, adjacent role.
Examples
The following example uses WideString
to get windows error messages, since FormatMessageW
returns a string length for us, and we don't need to pass error messages into other FFI
functions so we don't need to worry about nuls.
use winapi::*; use kernel32::{FormatMessageW, LocalFree}; use std::ptr; use widestring::WideString; let widestr: WideString; unsafe { // First, get a string buffer from some windows api such as FormatMessageW... let mut buffer: LPWSTR = ptr::null_mut(); let strlen = FormatMessageW(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_IGNORE_INSERTS, ptr::null(), error_code, // error code from GetLastError() 0, (&mut buffer as *mut LPWSTR) as LPWSTR, 0, ptr::null_mut()); // Get the buffer as a wide string widestr = WideString::from_ptr(buffer, strlen as usize); // Since WideString creates an owned copy, it's safe to free original buffer now // If you didn't want an owned copy, you could use &WideStr. LocalFree(buffer as HLOCAL); } // Convert to a regular Rust String and use it to your heart's desire! let message = widestr.to_string_lossy();
The following example is the functionally the same, only using WideCString
instead.
use winapi::*; use kernel32::{FormatMessageW, LocalFree}; use std::ptr; use widestring::WideCString; let widestr: WideCString; unsafe { // First, get a string buffer from some windows api such as FormatMessageW... let mut buffer: LPWSTR = ptr::null_mut(); FormatMessageW(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_IGNORE_INSERTS, ptr::null(), error_code, // error code from GetLastError() 0, (&mut buffer as *mut LPWSTR) as LPWSTR, 0, ptr::null_mut()); // Get the buffer as a wide string widestr = WideCString::from_ptr_str(buffer); // Since WideCString creates an owned copy, it's safe to free original buffer now // If you didn't want an owned copy, you could use &WideCStr. LocalFree(buffer as HLOCAL); } // Convert to a regular Rust String and use it to your heart's desire! let message = widestr.to_string_lossy();
Structs
MissingNulError |
An error returned from |
NulError |
An error returned from |
WideCStr |
C-style wide string reference for |
WideCString |
An owned, mutable C-style "wide" string for windows FFI that is nul-aware and nul-terminated. |
WideStr |
Wide string reference for |
WideString |
An owned, mutable "wide" string for windows FFI that is not nul-aware. |