String Operations

Low-level string-operation factory and supporting types. The chainable str_* methods on :class:~aerospike_sdk.aio.operations.query.WriteBinBuilder and :class:~aerospike_sdk.aio.operations.query.QueryBinBuilder (documented under QueryBuilder) cover the common cases; reach for the factory directly when you need to apply a string op to a value nested inside a CDT via ctx=[...].

See the String Operations guide for narrative examples.

class aerospike_sdk.StringOperation

Bases: object

String bin operations (server 8.2.0+). Use these to inspect or modify string bins via the client’s operate() method.

Index orientation is left-to-right with codepoint addressing. Negative indexes count from the end of the string (-1 = last codepoint). Out-of-bounds indexes are clamped to the valid range.

CTX navigation: every factory (except to_string) accepts an optional trailing ctx argument selecting a string element nested inside a list/map bin. With ctx=None the op targets the bin itself.

static append(bin, value, *, flags=0, ctx=None)

Append value to the end of the bin. Single-value form (server sub-op 67); use concat for the list form.

static b64_decode(bin, *, ctx=None)

Treat the bin as base64-encoded text and return the decoded bytes. Returns OP_NOT_APPLICABLE (subcode OPNOT_STRING_B64_INVALID) if the bin is not valid base64.

static byte_length(bin, *, ctx=None)

UTF-8 byte length (differs from strlen for non-ASCII content).

static case_fold(bin, *, flags=0, ctx=None)

Apply a locale-independent case fold (lowercase). Useful for normalized comparison keys.

static char_at(bin, index, *, ctx=None)

Codepoint at index as a one-codepoint string. Negative = from end.

static concat(bin, value, *, flags=0, ctx=None)

Append value to the bin. Accepts either a single string or a list of strings; the list form appends each element in order.

static contains(bin, needle, *, ctx=None)

True if the bin contains needle as a substring.

static ends_with(bin, suffix, *, ctx=None)

True if the bin ends with suffix.

static find(bin, needle, occurrence=None, *, ctx=None)

First-match codepoint index of needle (returns -1 if absent), or the N-th-match index when occurrence is given (1 = first match, -1 = last match).

static insert(bin, index, value, *, flags=0, ctx=None)

Splice value into the bin at codepoint index. Negative index counts from the end.

static is_lower(bin, *, ctx=None)

True if every cased codepoint is lowercase.

static is_numeric(bin, numeric_type=None, *, ctx=None)

True if the bin contains a valid number. Pass numeric_type to restrict to integer-only (StringNumericType.INT) or float-only (StringNumericType.FLOAT).

static is_upper(bin, *, ctx=None)

True if every cased codepoint is uppercase.

static lower(bin, *, flags=0, ctx=None)

Lowercase the bin in place.

static normalize_nfc(bin, *, flags=0, ctx=None)

Normalize the bin to Unicode NFC form. Already-normalized strings are unchanged.

static overwrite(bin, index, value, *, flags=0, ctx=None)

Overwrite codepoints starting at index with value. May extend past the original length.

static pad_end(bin, target_length, pad_string, *, flags=0, ctx=None)

Append pad_string repeatedly until the bin reaches target_length codepoints. No-op if already at or above target.

static pad_start(bin, target_length, pad_string, *, flags=0, ctx=None)

Prepend pad_string repeatedly until the bin reaches target_length codepoints. No-op if already at or above target.

static prepend(bin, value, *, flags=0, ctx=None)

Prepend value to the start of the bin. Distinct from insert(0, …) — this is the server’s dedicated prepend sub-op (68).

static regex_compare(bin, pattern, flags=0, *, ctx=None)

True if the ICU regex pattern matches the bin. flags is an OR-combined StringRegexFlags bitmask (or 0 for no flags).

static regex_replace(bin, pattern, replacement, flags=0, *, write_flags=0, ctx=None)

Replace the first match of pattern (ICU regex) with replacement. Pass StringRegexFlags.GLOBAL in flags to replace every match.

flags carries the regex flags; write_flags carries the StringWriteFlags bitmask (UPDATE_ONLY / NO_FAIL). The server rejects CREATE_ONLY here because a regex replace cannot create a bin.

static repeat(bin, count, *, flags=0, ctx=None)

Repeat the bin contents count times. count must be non-negative.

static replace(bin, needle, replacement, *, flags=0, ctx=None)

Replace the first occurrence of needle with replacement.

static replace_all(bin, needle, replacement, *, flags=0, ctx=None)

Replace every occurrence of needle with replacement.

static snip(bin, start, end=None, *, flags=0, ctx=None)

Remove the half-open codepoint range [start, end) from the bin, or everything from start through the end when end is None — snip("s", 5) truncates "hello world" to "hello".

flags require an explicit end. The server reads the snip arguments by position — start, end, then flags — so the 1-arg form is packed as [53, start] with no flags element; a 2-element [start, flags] wire would land the flags in the end slot and silently snip the empty range [start, 0).

static split(bin, separator=None, *, ctx=None)

Split the bin into a list of strings. With separator=None returns one element per codepoint.

static starts_with(bin, prefix, *, ctx=None)

True if the bin starts with prefix.

static strlen(bin, *, ctx=None)

Codepoint count (NOT byte count — use byte_length for bytes).

static substr(bin, start, end=None, *, ctx=None)

Substring from codepoint start to the end (when end is None), or the half-open range [start, end) (when end is given). Negative indexes count from the end; out-of-bounds clamp.

static to_blob(bin, *, ctx=None)

Return the UTF-8 bytes of the string as a blob.

static to_double(bin, *, ctx=None)

Parse the bin as a float (f64). Returns OP_NOT_APPLICABLE (subcode OPNOT_STRING_CONVERSION_FAILED) if unparseable.

static to_integer(bin, *, ctx=None)

Parse the bin as an integer. Returns OP_NOT_APPLICABLE (subcode OPNOT_STRING_CONVERSION_FAILED) if unparseable.

static to_string(bin)

Convert a bool, integer, float, string, or blob bin to its string representation. Returns BIN_TYPE_ERROR for any other bin type, and OP_NOT_APPLICABLE (subcode OPNOT_STRING_UTF8_INVALID) for a blob that is not valid UTF-8.

Note: to_string does NOT accept a CTX argument — the wire format is a top-level op with no payload, so there is no place to put a CTX path. To convert a value nested inside a list or map, extract the leaf with ListOperation / MapOperation first.

static trim(bin, *, flags=0, ctx=None)

Strip whitespace from both ends of the bin.

static trim_end(bin, *, flags=0, ctx=None)

Strip whitespace from the end of the bin.

static trim_start(bin, *, flags=0, ctx=None)

Strip whitespace from the start of the bin.

static upper(bin, *, flags=0, ctx=None)

Uppercase the bin in place.

class aerospike_sdk.StringWriteFlags

Bases: object

Per-operation write flags for string modify ops. Combine with bitwise OR.

CREATE_ONLY and UPDATE_ONLY are mutually exclusive; sending both is a server ParameterError.

CREATE_ONLY = StringWriteFlags.CREATE_ONLY

DEFAULT = StringWriteFlags.DEFAULT

NO_FAIL = StringWriteFlags.NO_FAIL

UPDATE_ONLY = StringWriteFlags.UPDATE_ONLY

class aerospike_sdk.StringRegexFlags

Bases: object

ICU regex flags for regex_compare and regex_replace. Combine with bitwise OR. Default is no flags.

CASE_INSENSITIVE = StringRegexFlags.CASE_INSENSITIVE

DEFAULT = StringRegexFlags.DEFAULT

DOTALL = StringRegexFlags.DOTALL

GLOBAL = StringRegexFlags.GLOBAL

MULTILINE = StringRegexFlags.MULTILINE

UNIX_LINES = StringRegexFlags.UNIX_LINES

class aerospike_sdk.StringNumericType

Bases: object

Numeric-type filter for StringOperation.is_numeric. Default ANY matches integers or floats; restrict to one or the other with INT / FLOAT.

ANY = StringNumericType.ANY

FLOAT = StringNumericType.FLOAT

INT = StringNumericType.INT