Struct harfbuzz::Buffer

pub struct Buffer { /* fields omitted */ }

A series of Unicode characters.

Adding Text

Since in Rust, a value of type &str must contain valid UTF-8 text, adding text to a Buffer is simple:

let mut b = Buffer::new();
b.add_str("Hello World");
assert_eq!(b.is_empty(), false);

or, more simply:

let b = Buffer::with("Hello World");
assert_eq!(b.is_empty(), false);

Segment Properties

In addition to the text itself, there are three important properties that influence how a piece of text is shaped:

• Direction: The direction in which the output glyphs flow. This is typically left to right or right to left. This is controlled via the set_direction method on Buffer.
• Script: Script is crucial for choosing the proper shaping behaviour for scripts that require it (e.g. Arabic) and the which OpenType features defined in the font to be applied. This is controlled via the set_script method on Buffer.
• Language: Languages are crucial for selecting which OpenType feature to apply to the buffer which can result in applying language-specific behaviour. Languages are orthogonal to the scripts, and though they are related, they are different concepts and should not be confused with each other. This is controlled via the set_language method on Buffer.

Additionally, Harfbuzz can attempt to infer the values for these properties using the guess_segment_properties method on Buffer:

let mut b = Buffer::with("مساء الخير");
b.guess_segment_properties();
assert_eq!(b.get_direction(), Direction::RTL);
assert_eq!(b.get_script(), sys::HB_SCRIPT_ARABIC);

Methods

impl Buffer

pub fn new() -> Self

Create a new, empty buffer.

let b = Buffer::new();
assert!(b.is_empty());

pub unsafe fn from_raw(raw: *mut hb_buffer_t) -> Self

Construct a Buffer from a raw pointer. Takes ownership of the buffer.

pub fn as_ptr(&self) -> *mut hb_buffer_t

Borrows a raw pointer to the buffer.

pub fn into_raw(self) -> *mut hb_buffer_t

Gives up ownership and returns a raw pointer to the buffer.

pub fn with(text: &str) -> Self

Create a new buffer with the given text.

pub fn with_capacity(capacity: usize) -> Self

Create a new, empty buffer with the specified capacity.

pub fn add_str(&mut self, text: &str)

Add UTF-8 encoded text to the buffer.

pub fn append(&mut self, other: &Buffer, start: usize, end: usize)

Append part of the contents of another buffer to this one.

let mut b1 = Buffer::with("butter");
let b2 = Buffer::with("fly");
b1.append(&b2, 0, 3);
assert_eq!(b1.len(), "butterfly".len());

pub fn clear_contents(&mut self)

Throw away text stored in the buffer, but maintain the currently configured Unicode functions and flags.

Text, glyph info, and segment properties will be discarded.

pub fn reset(&mut self)

Throw away all data stored in the buffer as well as configuration parameters like Unicode functions, flags, and segment properties.

pub fn reserve(&mut self, size: usize)

Preallocate space to fit at least size number of items.

FIXME: Does this correctly match the expected semantics?

pub fn len(&self) -> usize

Returns the number of elements in the buffer, also referred to as its 'length'.

pub fn is_empty(&self) -> bool

Returns true if the buffer contains no data.

pub fn guess_segment_properties(&mut self)

Sets unset buffer segment properties based on buffer Unicode contents.

If buffer is not empty, it must have content type HB_BUFFER_CONTENT_TYPE_UNICODE.

If buffer script is not set (ie. is HB_SCRIPT_INVALID), it will be set to the Unicode script of the first character in the buffer that has a script other than HB_SCRIPT_COMMON, HB_SCRIPT_INHERITED, and HB_SCRIPT_UNKNOWN.

Next, if buffer direction is not set (ie. is Direction::Invalid), it will be set to the natural horizontal direction of the buffer script as returned by hb_script_get_horizontal_direction().

Finally, if buffer language is not set (ie. is HB_LANGUAGE_INVALID), it will be set to the process's default language as returned by hb_language_get_default(). This may change in the future by taking buffer script into consideration when choosing a language.

let mut b = Buffer::with("Hello, world!");
b.guess_segment_properties();
assert_eq!(b.get_direction(), Direction::LTR);
assert_eq!(b.get_script(), sys::HB_SCRIPT_LATIN);

See also:

• get_direction
• set_direction
• get_script
• set_script
• get_language
• set_language

pub fn set_direction(&mut self, direction: Direction)

Set the text flow direction of the buffer.

No shaping can happen without setting buffer direction, and it controls the visual direction for the output glyphs; for RTL direction the glyphs will be reversed. Many layout features depend on the proper setting of the direction, for example, reversing RTL text before shaping, then shaping with LTR direction is not the same as keeping the text in logical order and shaping with RTL direction.

See also:

• get_direction
• guess_segment_properties

pub fn get_direction(&self) -> Direction

Get the text flow direction for the buffer.

See also:

• set_direction

pub fn set_script(&mut self, script: hb_script_t)

Sets the script of buffer to script.

Script is crucial for choosing the proper shaping behaviour for scripts that require it (e.g. Arabic) and the which OpenType features defined in the font to be applied.

See also:

• get_script
• guess_segment_properties

pub fn get_script(&self) -> hb_script_t

Get the script for the buffer.

See also:

• set_script

pub fn set_language(&mut self, language: Language)

Sets the language of buffer to language.

Languages are crucial for selecting which OpenType feature to apply to the buffer which can result in applying language-specific behaviour. Languages are orthogonal to the scripts, and though they are related, they are different concepts and should not be confused with each other.

See also:

• get_language
• guess_segment_properties

pub fn get_language(&self) -> Language

Get the language for the buffer.

See also:

• set_language

Trait Implementations

impl Drop for Buffer

fn drop(&mut self)

Executes the destructor for this type.

impl Default for Buffer

fn default() -> Self

Create a new, empty buffer.

impl Debug for Buffer

fn fmt(&self, fmt: &mut Formatter) -> Result

Formats the value using the given formatter.