NumPy strings.add() – Element-wise String Concatenation

NumPy strings.add()

The numpy.strings.add() function performs element-wise string concatenation on input arrays. If the arrays have different shapes, they must be broadcastable to a common shape.

Syntax

numpy.strings.add(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True)

Parameters

Parameter	Type	Description
x1, x2	array_like	Input string arrays to be concatenated. Must be broadcastable to a common shape.
out	ndarray, None, or tuple of ndarray and None, optional	Optional output array where the result is stored. If None, a new array is created.
where	array_like, optional	Boolean mask specifying where to perform concatenation. Unselected elements retain their original value.
casting	str, optional	Defines the casting behavior during computation.
order	str, optional	Memory layout order of the output array.
dtype	data-type, optional	Defines the data type of the output array.
subok	bool, optional	Determines if subclasses of ndarray are preserved in the output.

Return Value

Returns an array containing element-wise concatenated strings. If both inputs are scalars, a scalar is returned.

---

Examples

1. Concatenating Two String Scalars

Here, we concatenate two individual strings using numpy.strings.add().

import numpy as np

# Define two string scalars
str1 = "apple"
str2 = "banana"

# Concatenate using numpy.strings.add
result = np.strings.add(str1, str2)

# Print the result
print("Concatenated string:", result)

Output:

Concatenated string: applebanana

2. Concatenating Two String Arrays

We concatenate two arrays of strings element-wise.

import numpy as np

# Define two string arrays
arr1 = np.array(["apple", "banana", "cherry"])
arr2 = np.array([" pie", " smoothie", " tart"])

# Concatenate element-wise
result = np.strings.add(arr1, arr2)

# Print the result
print("Concatenated array:", result)

Output:

Concatenated array: ['apple pie' 'banana smoothie' 'cherry tart']

3. Concatenating with Broadcasting

We use broadcasting to concatenate a single string to all elements in an array.

import numpy as np

# Define a string array
fruits = np.array(["apple", "banana", "cherry"])

# Define a suffix to be added to all elements
suffix = " juice"

# Concatenate using broadcasting
result = np.strings.add(fruits, suffix)

# Print the result
print("Concatenated array:", result)

Output:

Concatenated array: ['apple juice' 'banana juice' 'cherry juice']

4. Using the out Parameter

Storing concatenated results in a preallocated output array.

import numpy as np

# Define two string arrays
arr1 = np.array(["apple", "banana", "cherry"])
arr2 = np.array([" tree", " split", " pie"])

# Create an output array with the same shape
output_array = np.empty_like(arr1, dtype="<U20")
# Perform element-wise concatenation with output array
np.strings.add(arr1, arr2, out=output_array)

# Print the results
print("Concatenated array:", output_array)

Output:

Concatenated array: ['apple tree' 'banana split' 'cherry pie']

5. Using the where Parameter

Concatenating only selected elements based on a condition.

import numpy as np

# Define two string arrays
arr1 = np.array(["apple", "banana", "cherry"])
arr2 = np.array([" pie", " split", " tart"])

# Define a condition (only concatenate the first and last element)
mask = np.array([True, False, True])

# Perform conditional concatenation
result = np.strings.add(arr1, arr2, where=mask)

# Print the results
print("Conditionally concatenated array:", result)

Output:

Conditionally concatenated array: ['apple pie' '' 'cherry tart']

Only elements where mask=True are concatenated.