Struct harfbuzz_rs::UnicodeBuffer

pub struct UnicodeBuffer(_);

A UnicodeBuffer can be filled with unicode text and corresponding cluster indices.

Usage

The buffer manages an allocation for the unicode codepoints to be shaped. This allocation is reused for storing the results of the shaping operation in a GlyphBuffer object. The intended usage is to keep one (or e.g. one per thread) UnicodeBuffer around. When needed, you fill it with text that should be shaped and pass it as an argument to the shape function. That method returns a GlyphBuffer object containing the shaped glyph indices. Once you got the needed information out of the GlyphBuffer you call its .clear() method which in turn gives you a fresh UnicodeBuffer (also reusing the original allocation again). This buffer can then be used to shape more text.

Interaction with the raw harfbuzz API

If you want to get a UnicodeBuffer from a pointer to a raw harfbuzz object, you need to use the from_raw static method on TypedBuffer. This ensures that a buffer of correct type is created.

Implementations

impl UnicodeBuffer

pub fn new() -> UnicodeBuffer

Creates a new empty Buffer.

Examples

use harfbuzz_rs::UnicodeBuffer;

let buffer = UnicodeBuffer::new();
assert!(buffer.is_empty());

pub fn into_raw(self) -> *mut hb_buffer_t

Converts this buffer to a raw harfbuzz object pointer.

pub fn len(&self) -> usize

Returns the length of the data of the buffer.

This corresponds to the number of unicode codepoints contained in the buffer.

Examples

use harfbuzz_rs::UnicodeBuffer;

let str1 = "Hello ";
let buffer = UnicodeBuffer::new().add_str(str1);
assert_eq!(buffer.len(), str1.len());

let str2 = "😍🙈";
let buffer = buffer.add_str(str2);
assert_eq!(buffer.len(), str1.len() + 2);;

pub fn is_empty(&self) -> bool

Returns true if the buffer contains no elements.

pub fn add(self, codepoint: u32, cluster: u32) -> UnicodeBuffer

Add a single codepoint with the associated cluster value to the buffer.

Examples

use harfbuzz_rs::UnicodeBuffer;

let buffer = UnicodeBuffer::new().add('A' as u32, 0);
assert_eq!(buffer.string_lossy(), "A");

pub fn add_str(self, str_slice: &str) -> UnicodeBuffer

Add the string slice str_slice to the Buffer's array of codepoints.

When shaping part of a larger text (e.g. a run of text from a paragraph) it is preferable to use add_str_item instead.

Examples

use harfbuzz_rs::UnicodeBuffer;

let buffer = UnicodeBuffer::new().add_str("Hello");
let buffer = buffer.add_str(" World");
assert_eq!(buffer.string_lossy(), "Hello World");

pub fn add_str_item(self, context: &str, item: &str) -> UnicodeBuffer

Add a string item to the buffer, providing context.

Only the item string gets added to the buffer and will be shaped. context provides extra information to the shaper, allowing, for example, to do cross-run Arabic shaping or properly handle combining marks at the start of a run.

When shaping part of a larger text (e.g. a run of text from a paragraph) you should pass the whole paragraph to this function as context whereas item refers only to the part of the string to be shaped.

Panics

Panics if item is not a substring of context. Note that item must reside in the same allocation as context!

Examples

We only want to shape the string World as part of the sentence Hello World!.

use harfbuzz_rs::UnicodeBuffer;

let string = "Hello World!";

// the range 6..11 corresponds to `World`
assert_eq!(&string[6..11], "World");

let buffer = UnicodeBuffer::new().add_str_item(string, &string[6..11]);
assert_eq!(buffer.string_lossy(), "World");

pub fn append(self, other: &UnicodeBuffer) -> UnicodeBuffer

Append codepoints from another UnicodeBuffer to the end of self.

Examples

use harfbuzz_rs::UnicodeBuffer;

let buffer = UnicodeBuffer::new().add_str("Hello");
let other = UnicodeBuffer::new().add_str(" World!");
let buffer = buffer.append(&other);
assert_eq!(buffer.string_lossy(), "Hello World!");

pub fn append_range(
    self,
    other: &UnicodeBuffer,
    range: impl RangeBounds<usize>
) -> UnicodeBuffer

Append a range of codepoints from another UnicodeBuffer to the end of self.

Examples

use harfbuzz_rs::UnicodeBuffer;

let buffer = UnicodeBuffer::new().add_str("Hello");
let other = UnicodeBuffer::new().add_str(" World!");
let buffer = buffer.append_range(&other, 0..=3);
assert_eq!(buffer.string_lossy(), "Hello Wor");
let buffer = buffer.append_range(&other, 4..);
assert_eq!(buffer.string_lossy(), "Hello World!");

pub fn codepoints(&self) -> Codepointsⓘ

Important traits for Codepoints<'a>

impl<'a> Iterator for Codepoints<'a> type Item = u32;

Returns an Iterator over the stored unicode codepoints.

Examples

use harfbuzz_rs::UnicodeBuffer;

let buffer = UnicodeBuffer::new().add_str("ab");
let mut iterator = buffer.codepoints();

assert_eq!('a' as u32, iterator.next().unwrap());
assert_eq!('b' as u32, iterator.next().unwrap());
assert!(iterator.next().is_none());

pub fn string_lossy(&self) -> String

Get the stored codepoints as a String.

Invalid codepoints get replaced by the U+FFFD replacement character.

pub fn set_direction(self, direction: Direction) -> UnicodeBuffer

Set the text direction of the Buffer's contents.

pub fn get_direction(&self) -> Direction

Returns the Buffer's text direction.

pub fn set_script(self, script: Tag) -> UnicodeBuffer

Set the script from an ISO15924 tag.

pub fn get_script(&self) -> Tag

Get the ISO15924 script tag.

pub fn set_language(self, lang: Language) -> UnicodeBuffer

Set the buffer language.

pub fn get_language(&self) -> Option<Language>

Get the buffer language.

pub fn guess_segment_properties(self) -> UnicodeBuffer

Guess the segment properties (direction, language, script) for the current buffer.

pub fn get_segment_properties(&self) -> SegmentProperties

Get the segment properties (direction, language, script) of the current buffer.

pub fn set_cluster_level(self, cluster_level: ClusterLevel) -> UnicodeBuffer

Set the cluster level of the buffer.

pub fn get_cluster_level(&self) -> ClusterLevel

Retrieve the cluster level of the buffer.

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

Pre-allocate the buffer to hold a string at least size codepoints.

pub fn clear_contents(self) -> UnicodeBuffer

Clear the contents of the buffer (i.e. the stored string of unicode characters).

Examples

use harfbuzz_rs::UnicodeBuffer;

let buffer = UnicodeBuffer::new();
let buffer = buffer.add_str("Test!");
assert_eq!(buffer.len(), 5);
let buffer = buffer.clear_contents();
assert!(buffer.is_empty());

Trait Implementations

impl Debug for UnicodeBuffer

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

Formats the value using the given formatter.

impl Default for UnicodeBuffer

fn default() -> UnicodeBuffer

Returns the "default value" for a type.