# guardStringIncludesSome()

## `guardStringIncludesSome()`

Guards the value to be a [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) type or an instance of [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) that **includes** **some** of the specified **words/sentences**.

{% code title="guard-string-includes-some.func.ts" %}

```typescript
const guardStringIncludesSome = <
  Type extends AnyString,
  Payload extends object = object
>(
  value: Type,
  includes: string[],
  callback: ResultCallback<
    Type,
    { includes: typeof includes } & Payload
  > = resultCallback,
  payload?: Payload
): value is Type => isStringIncludesSome(value, includes, callback, payload);
```

{% endcode %}

### Generic type variables

#### <mark style="color:green;">**`Type`**</mark>**`extends`**<mark style="color:green;">**`AnyString`**</mark>

A generic type variable `Obj` constrained by [`AnyString`](https://docs.angular-package.dev/type/type/anystring) indicates captured [`string`](https://www.typescriptlang.org/docs/handbook/basic-types.html#string) type of the given [`value`](#value-type) via the [return type](#return-type) and the [`value`](https://docs.angular-package.dev/type/type/resultcallback#value-value) parameter of the provided [`callback`](#callback-resultcallback-less-than-type-includes-typeof-includes-and-payload-greater-than) function [`ResultCallback`](https://docs.angular-package.dev/type/type/resultcallback) type.

#### <mark style="color:green;">**`Payload`**</mark>**`extends`**<mark style="color:green;">**`object`**</mark>**`=`**<mark style="color:green;">**`object`**</mark>

The `Payload` generic type variable constrained by [`object`](https://www.typescriptlang.org/docs/handbook/basic-types.html#object) indicates the type of optional parameter [`payload`](https://docs.angular-package.dev/type/type/resultcallback#payload-payload) of the supplied [`callback`](#callback-resultcallback-less-than-type-includes-typeof-includes-and-payload-greater-than) function and [`payload`](#payload-payload) optional parameter of the [`guardStringIncludesSome()`](#guardstringincludessome) function from which it captures its value.

### Parameters

#### `value: Type`

The value of a generic type variable [`Type`](#typeextendsanystring) constrained by the [`AnyString`](https://docs.angular-package.dev/type/type/anystring), by default of the type captured from itself to check against the [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) that contains **some** of the **words/sentences** from a given [`includes`](#includes-string).

#### `includes: string[]`

An [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) of [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) as **words/sentences** to be **case-sensitive** searched for within a given [`value`](#value-type).

#### `callback?: ResultCallback<Type, { includes: typeof includes } & Payload>`

The optional callback [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Functions) of [`ResultCallback`](https://docs.angular-package.dev/type/type/resultcallback) type with parameters, the [`value`](#value-type) that has been checked, the `result` of this check, and `payload` of generic type variable [`Payload`](#payloadextendsobject) with optional properties from the provided `payload`, to handle them before the `result` return. By default, it uses `resultCallback()` function.

{% hint style="info" %}
The **`payload`** parameter of given [`callback`](#callback-resultcallback-less-than-type-includes-typeof-includes-and-payload-greater-than) function consists of the **`includes`** property of the given [`includes`](#includes-string), and it can't be overwritten by the given [`payload`](#payload-payload) parameter of the main function.
{% endhint %}

#### `payload?: Payload`

An optional [`object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) of the generic type variable [`Payload`](#payloadextendsobject-object) is assigned to the [`payload`](https://docs.angular-package.dev/type/type/resultcallback#payload-payload) of the given [`callback`](#callback-resultcallback-less-than-type-includes-typeof-includes-and-payload-greater-than) function.

### Return type

#### `value is Type`

The **return type** is a [`boolean`](https://www.typescriptlang.org/docs/handbook/basic-types.html#boolean) as the result of its statement indicating the [`value`](#value-type) is a generic type variable [`Type`](#typeextendsanystring) by default of the type captured from the [`value`](#value-type).

### Returns

The **return value** is a [`boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) indicating whether the provided [`value`](#value-type) is a [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) type or an instance of [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) that includes **some** of the specified **words/sentences**.

## Example usage

```typescript
// Example usage.
import { guardStringIncludesSome } from '@angular-package/type';

// true; The return type `value is "This is a person without age."`
guardStringIncludesSome('This is a person without age.', ['age']);
// false; The return type `value is "This is a person without age."`
guardStringIncludesSome('This is a person without age.', ['Person']);
// true; The return type `value is "This is a person without age."`
guardStringIncludesSome('This is a person without age.', ['age', 'Person']);
// true; The return type `value is String`
guardStringIncludesSome(new String('This is artificial intelligence.'), [
'artificial',
'intelligence',
]);
```