pow2

Base 2 exponentiation and scaling of floating-point numbers

Syntax

Y = pow2(E)

Y = pow2(X,E)

Description

Y = pow2(E) computes 2 to the power of E such that $$Y=2^E$$.

Y = pow2(X,E) computes X times 2 to the power of an integer E such that $$Y=X\cdot 2^E$$. If E is not an integer, then this syntax rounds E to the nearest integer toward zero such that $$Y=X\cdot 2^{\text{fix}(E)}$$.

Examples

Exponentiation

Raise 2 to the power of E.

E = [1 -2 4 -4 3 9];
Y = pow2(E)

Y = 1×6

    2.0000    0.2500   16.0000    0.0625    8.0000  512.0000

Scale Significands by 2 Raised to Power of Exponents

In this example, compare the standard IEEE® arithmetic results of scaling significands by 2 raised to the power of exponents and the pow2 results.

Create a cell array of character vectors to represent the exact values of several significands. Specify the exponents.

Xcell = {'1/2','pi/4','-3/4','1/2','1-eps/2','1/2'}';
E = [1 2 2 -51 1024 -1021]';

Specify Ycell as the standard IEEE arithmetic results of scaling Xcell by 2 raised to the power of E. Show these results in a table.

Ycell = {'1','pi','-3','eps','realmax','realmin'}';
table(Xcell,E,Ycell,'VariableNames',["Significand" "Exponent" "Value"])

ans=6×3 table
    Significand    Exponent       Value   
    ___________    ________    ___________

    {'1/2'    }         1      {'1'      }
    {'pi/4'   }         2      {'pi'     }
    {'-3/4'   }         2      {'-3'     }
    {'1/2'    }       -51      {'eps'    }
    {'1-eps/2'}      1024      {'realmax'}
    {'1/2'    }     -1021      {'realmin'}

Next, compare the results in the table to pow2.

Convert Xcell to floating-point numbers X. Scale X by 2 raised to the power of E by using pow2(X,E).

X = str2num(char(Xcell));
Y = pow2(X,E)

Y = 6×1
10308 ×

    0.0000
    0.0000
   -0.0000
    0.0000
    1.7977
    0.0000

Convert Ycell to floating-point numbers Ynum. Show that pow2 follows the standard IEEE arithmetic operations by comparing Y and Ynum using isequal.

Ynum = str2num(char(Ycell))

Ynum = 6×1
10308 ×

    0.0000
    0.0000
   -0.0000
    0.0000
    1.7977
    0.0000

isequal(Y,Ynum)

ans = logical
   1

Input Arguments

E — Exponent values

scalar | vector | matrix | multidimensional array | table | timetable

Exponent values, specified as a scalar, vector, matrix, multidimensional array, table, or timetable.

Data Types: single | double | table | timetable

X — Significand values

scalar | vector | matrix | multidimensional array | table | timetable

Significand values, specified as a scalar, vector, matrix, or multidimensional array of the same size as E.

Data Types: single | double | table | timetable

Tips

The syntax Y = pow2(X,E) corresponds to the ANSI^® C function ldexp() and the IEEE^® floating-point standard function scalbn(). The result Y is computed quickly by simply adding E to the floating-point exponent of X.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The pow2 function fully supports tall arrays. For more information, see Tall Arrays.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The pow2 function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2025a: Complex inputs for two-input syntax will not be accepted

The pow2 function issues a warning if you specify complex inputs when using the two-input syntax. Support for complex inputs in this syntax will be removed in a future release. In previous releases, the two-input syntax ignored the imaginary parts of complex inputs and processed only the real parts.

To preserve the behavior of previous releases, use the real function to extract the real parts of complex inputs, as shown in this table.

Not Recommended (Warns)	Recommended
X = 2 + 1i; E = 2i; Y = pow2(X,E);	X = 2 + 1i; E = 2i; Y = pow2(real(X),real(E));

R2023a: Perform calculations directly on tables and timetables

The pow2 function can calculate on all variables within a table or timetable without indexing to access those variables. All variables must have data types that support the calculation. For more information, see Direct Calculations on Tables and Timetables.