FlixelString

View source

class

org.flixelgdx.util.FlixelString

public class FlixelString implements CharSequence

Reusable mutable text buffer backed by libGDX CharArray, designed to display changing values (health, FPS, velocity) every frame without allocating garbage.

Why not StringBuilder?

StringBuilder.append(...) internally calls Float.toString(...), which allocates a new String on every invocation. At 60 frames per second, even a single HUD counter can produce hundreds of short-lived strings per second that pressure the garbage collector. CharArray writes digits directly into its backing char[] with no intermediate String, so FlixelString.set(float), FlixelString.concat(float), and all other primitive overloads on this class are allocation-free on the hot path.

The same applies to int, long, double, boolean, char, byte, and short: every primitive FlixelString.set(CharSequence) and FlixelString.concat(CharSequence) overload goes through CharArray appenders rather than Object.toString().

Allocation-free float formatting

FlixelString.setFloatRounded(float, int) and FlixelString.concatFloatRounded(float, int) delegate to FlixelStringUtil.appendFloatRounded(...), which formats a float to any number of decimal places using only integer arithmetic, meaning no String is created at any point. FlixelString.setFloatRoundedOneDecimal(float) and FlixelString.concatFloatRoundedOneDecimal(float) are convenience variants for exactly one decimal place.

Passing to libGDX drawing APIs

This class implements CharSequence, so instances can be passed directly to APIs such as BitmapFont.draw without building a temporary String. Avoid calling FlixelString.toString() or using string concatenation on this type in per-frame code: both allocate. Pass this as a CharSequence instead.

set() vs concat()

FlixelString.set(CharSequence) clears the buffer and writes new content in one call, which is the typical pattern for a HUD label that shows a single changing value. FlixelString.concat(CharSequence) appends without clearing, which is useful when building a line from multiple parts. FlixelString.charBuffer() exposes the raw CharArray for advanced interop with libGDX APIs that require it directly.

Example Usage

// Create a new FlixelString with a capacity of 32 characters.
// Because it implements CharSequence, it can be used as a parameter
// for methods that expect a CharSequence, like FlixelText.
FlixelString fs = new FlixelString(32);
FlixelText ft = new FlixelText();

// In your update loop...
@Override
public void update(float elapsed) {
  // Below would be the same equivalent of doing ft.setText("Score: " + score),
  // except it doesn't allocate new strings every frame and keeps your
  // framerate silky smooth!
  fs.set("Score: ");
  fs.concat(score);
  ft.setText(fs);
}

Constructors

FlixelString()

public FlixelString()

Creates an empty buffer with a default initial capacity.

---

FlixelString(int)

public FlixelString(int initialCapacity)

Creates an empty buffer with the given initial capacity hint.

Parameters:

Name	Description
initialCapacity	Non-negative initial capacity for the backing CharArray.

---

FlixelString(CharSequence)

public FlixelString(CharSequence text)

Creates a buffer whose content is a copy of text.

Parameters:

Name	Description
text	Source characters; null is treated like the literal "null".

---

Methods

charBuffer()

public CharArray charBuffer()

Returns the mutable backing CharArray. Callers must not retain references across frames if the owning FlixelString is reused or pooled, because the buffer contents change in place.

Returns: The internal CharArray (never null).

---

clear()

public void clear()

Clears all characters without shrinking the allocated buffer.

See Also: CharArray.clear()

---

shrinkToFit()

public void shrinkToFit()

Shrinks the allocated buffer to the current length.

See Also: CharArray.shrink()

---

trimToSize()

public void trimToSize()

Trims the internal storage to the current length. Suitable for teardown paths (for example FlixelText.destroy()) but not for per-frame use.

---

isEmpty()

public boolean isEmpty()

Returns: true when the buffer contains no characters.

---

getEmpty()

public boolean getEmpty()

Returns whether the buffer contains no characters.

---

set(CharSequence)

public FlixelString set(CharSequence text)

Replaces the entire buffer with a copy of text.

Parameters:

Name	Description
text	New content; null is treated like the literal "null".

Returns: this for chaining.

---

set(FlixelString)

public FlixelString set(FlixelString other)

Replaces the buffer with a copy of another FlixelString.

Parameters:

Name	Description
other	Source buffer; null is treated like the literal "null" via FlixelString.set(CharSequence).

Returns: this for chaining.

---

set(boolean)

public FlixelString set(boolean value)

Returns: this after replacing content with value.

---

set(char)

public FlixelString set(char value)

Returns: this after replacing content with value.

---

set(byte)

public FlixelString set(byte value)

Returns: this after replacing content with the decimal rendering of value.

---

set(short)

public FlixelString set(short value)

Returns: this after replacing content with the decimal rendering of value.

---

set(int)

public FlixelString set(int value)

Returns: this after replacing content with the decimal rendering of value.

---

set(long)

public FlixelString set(long value)

Returns: this after replacing content with the decimal rendering of value.

---

set(float)

public FlixelString set(float value)

Returns: this after replacing content with the decimal rendering of value.

---

set(double)

public FlixelString set(double value)

Returns: this after replacing content with the decimal rendering of value.

---

concat(CharSequence)

public FlixelString concat(CharSequence other)

Appends the content of other to the buffer.

Note: If the other is a String, it will be converted to a CharSequence using String.subSequence(...).

Parameters:

Name	Description
other	The CharSequence to append.

Returns: this for chaining.

---

concat(FlixelString)

public FlixelString concat(FlixelString other)

Appends the content of other to the buffer.

Parameters:

Name	Description
other	The FlixelString to append.

Returns: this for chaining.

---

concat(boolean)

public FlixelString concat(boolean value)

Appends the content of value to the buffer.

Parameters:

Name	Description
value	The boolean value to append.

Returns: this for chaining.

---

concat(char)

public FlixelString concat(char value)

Appends the content of value to the buffer.

Parameters:

Name	Description
value	The char value to append.

Returns: this for chaining.

---

concat(byte)

public FlixelString concat(byte value)

Appends the content of value to the buffer.

Parameters:

Name	Description
value	The byte value to append.

Returns: this for chaining.

---

concat(short)

public FlixelString concat(short value)

Appends the content of value to the buffer.

Parameters:

Name	Description
value	The short value to append.

Returns: this for chaining.

---

concat(int)

public FlixelString concat(int value)

Appends the content of value to the buffer.

Parameters:

Name	Description
value	The int value to append.

Returns: this for chaining.

---

concat(long)

public FlixelString concat(long value)

Appends the content of value to the buffer.

Parameters:

Name	Description
value	The long value to append.

Returns: this for chaining.

---

concat(float)

public FlixelString concat(float value)

Appends the content of value to the buffer.

Parameters:

Name	Description
value	The float value to append.

Returns: this for chaining.

---

concat(double)

public FlixelString concat(double value)

Appends the content of value to the buffer.

Parameters:

Name	Description
value	The double value to append.

Returns: this for chaining.

---

concatFloatRounded(float, int)

public FlixelString concatFloatRounded(float value, int decimals)

Appends value rounded to decimals decimal places using the same rules as FlixelStringUtil.appendFloatRounded(...). Does not clear the buffer first.

When decimals is zero or negative, the value is rounded to the nearest integer and no decimal point is written. Fractional digits are zero-padded on the left so the output always contains exactly decimals digits after the decimal point.

Parameters:

Name	Description
value	Value to append (non-finite values use CharArray.append(...)).
decimals	Number of digits after the decimal point; values of zero or less produce an integer with no decimal point.

Returns: this for chaining.

---

concatFloatRoundedOneDecimal(float)

public FlixelString concatFloatRoundedOneDecimal(float value)

Appends value rounded to one decimal place (tenths). Convenience wrapper for FlixelString.concatFloatRounded(float, int) with decimals = 1.

Parameters:

Name	Description
value	Value to append (non-finite values use CharArray.append(...)).

Returns: this for chaining.

---

concat(Object)

public FlixelString concat(Object obj)

Appends an object the same way CharArray.append(...) does: null becomes the literal "null", CharSequence is appended without Object.toString(), and other types use Object.toString().

Parameters:

Name	Description
obj	Value to append (may be null).

Returns: this for chaining.

---

setCharSequence(Supplier<? extends CharSequence>)

public FlixelString setCharSequence(Supplier<? extends CharSequence> supplier)

Replaces the buffer with the CharSequence returned by supplier. If the supplier returns null, the literal "null" is appended.

Note: If the supplier constructs a new String on each call, allocations move to the supplier. Prefer CharSequence sources that are stable or reused when possible.

Parameters:

Name	Description
supplier	Source of the new content; must not be null.

Returns: this for chaining.

---

setFloatRounded(float, int)

public FlixelString setFloatRounded(float value, int decimals)

Clears the buffer and writes value rounded to decimals decimal places using only CharArray primitive appenders, avoiding Float.toString(...) and similar helpers that allocate String instances.

When decimals is zero or negative, the value is rounded to the nearest integer and no decimal point is written. Fractional digits are zero-padded on the left so the output always contains exactly decimals digits after the decimal point.

Parameters:

Name	Description
value	Value to format; non-finite values fall back to CharArray.append(...).
decimals	Number of digits after the decimal point; values of zero or less produce an integer with no decimal point.

Returns: this for chaining.

---

setFloatRoundedOneDecimal(float)

public FlixelString setFloatRoundedOneDecimal(float value)

Clears the buffer and writes value rounded to one decimal place (tenths). Convenience wrapper for FlixelString.setFloatRounded(float, int) with decimals = 1.

Parameters:

Name	Description
value	Value to format. Non-finite values fall back to CharArray.append(...).

Returns: this for chaining.

---

copyContentToNewString()

public String copyContentToNewString()

Copies the current buffer into a new String. Intended for cold paths (for example a debug forEach callback), not per-frame drawing.

Returns: A new string holding the current characters.

---

length()

public int length()

---

charAt(int)

public char charAt(int index)

---

subSequence(int, int)

public CharSequence subSequence(int start, int end)

---

toString()

public String toString()

Allocation warning: Builds a new String. Do not use on hot paths; pass this instance as a CharSequence instead where possible.

---