REPLACEB

What it does

REPLACEB(old_text, start_num, num_bytes, new_text)

REPLACEB(old_text, start_num, num_bytes, new_text) returns old_text with the window of num_bytes bytes beginning at byte position start_num removed and new_text put in its place. Byte positions are counted from 1.

It differs from REPLACE in exactly one respect — the unit in which the window is addressed — and that difference only exists under one condition. Microsoft's rule for the whole B family:

The B functions count each double-byte character as 2 only when a DBCS language has been enabled for editing and set as the default language. Otherwise they count each character as 1.

On a machine whose default editing language is not one of the DBCS languages, REPLACEB is REPLACE. On a machine whose default is Japanese, Chinese or Korean, the same formula addresses a different window of the same string. The active language is an unlisted input to this function.

The bytes are those of the DBCS code page for the active language — Shift-JIS, GBK, Big5, EUC-KR — not UTF-8 and not UTF-16.

Arguments

All four are required. The signature is REPLACE's with num_chars renamed; the arity and positions are identical.

new_text is inserted as text, not as bytes. There is no requirement that its byte length match num_bytes, and no documented rule connecting the two.

Try it

Quirks

Result and edge cases

Returns Text.

Microsoft's REPLACE, REPLACEB page states the signature and argument meanings and does not enumerate boundary behaviours. Everything below the signature is therefore unverified here.

The distinctively REPLACEB question is the one the documentation does not touch: what happens when start_num or start_num + num_bytes falls inside a double-byte character rather than on its boundary. Overwriting half of a character has no obviously correct answer — drop the partial character, keep its orphaned byte, round the boundary outward, error — and Microsoft names none of them. Under DBCS this is not exotic: any arithmetic on byte offsets over mixed-width text reaches it on the first mixed string.

Errors

Microsoft's page carries no error table for REPLACEB. The reachable errors are the shared ones: an error value in any argument propagates, and non-numeric text in start_num or num_bytes surfaces #VALUE! under the shared coercion rules. Whether a partial-character window is an error condition is exactly the open question above.

How to implement

Notes for implementers

REPLACEB inherits everything hard about REPLACE — three-piece reconstruction, growth past the text cap, edges of the window past the end of the string — and adds the byte question on top.

The practical consequence for verification: a REPLACEB test vector that does not record the default editing language is not a test vector. The same inputs legitimately produce two different correct answers.

The mixed-unit boundary deserves an explicit, recorded decision. old_text arrives as UTF-16 code units; start_num and num_bytes are code-page bytes; new_text arrives as UTF-16 again. An implementation is converting between two coordinate systems on every call, and a partial-character window is where the conversion stops being a bijection.

Rust code

25 replaceb_fn "REPLACEB" (4, 4) [V "old_text", V "start_num", V "num_bytes", V "new_text"] |s, a, sv| {
    single_byte(s)?;
    replace(s, a, true)
}

No implementation has been published with a Handbook test suite for this function.

Version differences

No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.

Alternatives

Relationships

• REPLACE — the character-addressed twin, documented by Microsoft on the same page. The Handbook publishes them as two entries because they address in two different units.
• SUBSTITUTE — the by-content alternative, and the one to reach for under DBCS, because matching a substring sidesteps byte-offset arithmetic entirely. There is no SUBSTITUTEB; the by-content route simply does not need one.
• LENB and FINDB are the functions that make REPLACEB usable at all, because they are the only ones that produce coordinates in the same byte space.

Named variants

No named variants are recorded yet.