String

struct String

Extends String to support the Action Data controls and adds convenience methods for working with NSImage and NSColor properties in a Codable, Encodable or Decodable class.

Examples:

// Get the hex representation of a color in macOS.
let hex: String ~= NSColor.white

Custom Operators

~=(_:_:)
Sets the String from the given NSColor where the color is converted to a hex string in the format #rrggbbaa where:
- rr - Specifies the red component as a hex value in the range 00 to FF.
- gg - Specifies the green component as a hex value in the range 00 to FF.
- bb - Specifies the blue component as a hex value in the range 00 to FF.
- aa - Specifies the alpha component as a hex value in the range 00 to FF.
Examples:
```
// Get the hex representation of a color in macOS.
let hex: String ~= NSColor.white
```
Declaration
Swift

public static func ~= ( left: inout String, right: NSColor)


                    
                    
                    ~=(_:_:)

Sets the String from the given NSImage where the image is converted to a PNG representation and Base 64 encoded.

Examples:

// Get the Base 64 representation of an image in macOS.
let hex: String ~= NSImage(named: "Background.png")

Declaration

Swift

public static func ~= ( left: inout String, right: NSImage)

Public Functions

nsColor
Attempts to convert the String into a NSColor if it is in the format rrggbb or rrggbbaa where:
- rr - Specifies the red component as a hex value in the range 00 to FF.
- gg - Specifies the green component as a hex value in the range 00 to FF.
- bb - Specifies the blue component as a hex value in the range 00 to FF.
- aa - Specifies the alpha component as a hex value in the range 00 to FF.
## Examples:
```
 // Get the hex representation of a color in macOS.
 let hex: String ~= NSColor.white
 let color = hex.nsColor
```
The hex string can optionally start with the prefix of #. If the String cannot be converted to a NSImage, nil is returned.
Declaration
Swift

public var nsColor: NSColor?


                    
                    
                    nsImage

If the String contains a Base 64 encoded representation of an image it is returns as a NSImage, else nil is returned.

Examples:

// Get the Base 64 representation of an macOS.
let hex: String ~= NSImage(named: "Background.png")
let image = hex.nsImage

Declaration

Swift

public var nsImage: NSImage?

Initializers


                    
                    
                    init(fromColor:)

Initializes a String instance from a given NSColor stored in the format #rrggbbaa where:

rr - Specifies the red component as a hex value in the range 00 to FF.
gg - Specifies the green component as a hex value in the range 00 to FF.
bb - Specifies the blue component as a hex value in the range 00 to FF.
aa - Specifies the alpha component as a hex value in the range 00 to FF.

Examples:

// Get the hex representation of a color in macOS.
let hex = String(fromColor: NSColor.white)

Declaration

Swift

public init(fromColor color: NSColor)

Parameters


                                color

The given NSColor to convert to a hex string.


                    
                    
                    init(fromImage:)

Initializes a String instance from a given NSImage where the image is converted to a PNG representation and Base 64 encoded.

Examples:

// Get the Base 64 representation of an image in macOS.
let hex = String(fromImage: NSImage(named: "Background.png"))

Declaration

Swift

public init(fromImage image: NSImage)


                    
                    
                    typeName(of:)

Returns a pretty-printed type name (minus the module name) for the given value.

Example:

// Assings a pretty type name
let name = String.typeName(of: "<module>")

Declaration

Swift

public static func typeName(of value: Any) -> String

Parameters


                                value

The value to get the type name of.

Return Value

The type name minus the module name.

height(withConstrainedWidth:font:)
Returns the draw height of the string in the given font constrained to the given width.

Example:
```
// Get a string height in macOS
let font = NSFont.systemFont(ofSize: 34, weight: NSFontWeightThin)
let text = "Hello World"
let height = text.height(withConstrainedWidth: 250, font: font)
```
- width: The pixel width to constrain the string to.
- font: The font that the string will be drawn in.
Declaration
Swift

public func height(withConstrainedWidth width: CGFloat, font: NSFont) -> CGFloat
Return Value

The height of the string drawn in the given font constrained to the given width.
width(withConstrainedHeight:font:)
Returns the draw width of the string in the given font constrained to the given height.

Example:
```
// Get a string height in macOS
let font = NSFont.systemFont(ofSize: 34, weight: NSFontWeightThin)
let text = "Hello World"
let height = text.width(withConstrainedHeight: 50, font: font)
```
- height: The pixel height to constrain the string to.
- font: The font that the string will be drawn in.
Declaration
Swift

public func width(withConstrainedHeight height: CGFloat, font: NSFont) -> CGFloat
Return Value

The width of the string drawn in the given font constrained to the given height.
bounds(withConstrainedSize:font:)
Returns the drawing bounds of the string in the given font constrained to the given maximum bounds.

Example:
```
// Get a string height in iOS, tvOS and watchOS
let font = NSFont.systemFont(ofSize: 34, weight: NSFontWeightThin)
let text = "Hello World"
let bounds = text.bounds(withConstrainedSize: GGSize(width: 250, height: 50), font: font)
```
- size: The maximum pixel width and height on the string.
- font: The font that the string will be drawn in.
Declaration
Swift

public func bounds(withConstrainedSize size: CGSize, font: NSFont) -> CGSize
Return Value

The bounds on the string drawn in the given font constrained to the given maximum bounds.